########
Language
########


****
NAME
****


Kernel::Language - global language interface


***********
DESCRIPTION
***********


All language functions.


****************
PUBLIC INTERFACE
****************


new()
=====


create a language object. Do not use it directly, instead use:


.. code-block:: perl

     use Kernel::System::ObjectManager;
     local $Kernel::OM = Kernel::System::ObjectManager->new(
         'Kernel::Language' => {
             UserLanguage => 'de',
         },
     );
     my $LanguageObject = $Kernel::OM->Get('Kernel::Language');



Translatable()
==============


this is a no-op to mark a text as translatable in the Perl code.

Example:


.. code-block:: perl

     my $Selection = $LayoutObject BuildSelection (
         Data => {
             'and' => Translatable('and'),
             'or'  => Translatable('or'),
             'xor' => Translatable('xor'),
         },
         Name        => "ConditionLinking[_INDEX_]",
         Sort        => 'AlphanumericKey',
         Translation => 1,
         Class       => 'Modernize W50pc',
     );



Translate()
===========


translate a text with placeholders.


.. code-block:: perl

     my $Text = $LanguageObject->Translate('Hello %s!', 'world');



FormatTimeString()
==================


formats a timestamp according to the specified date format for the current
language (locale).


.. code-block:: perl

     my $Date = $LanguageObject->FormatTimeString(
         '2009-12-12 12:12:12',  # timestamp
         'DateFormat',           # which date format to use, e. g. DateFormatLong
         0,                      # optional, hides the seconds from the time output
     );


Please note that the TimeZone will not be applied in the case of DateFormatShort (date only)
to avoid switching to another date.

If you only pass an ISO date ('2009-12-12'), it will be returned unchanged.
Invalid strings will also be returned with an error logged.


GetRecommendedCharset()
=======================


DEPRECATED. Don't use this function any more, 'utf-8' is always the internal charset.

Returns the recommended charset for frontend (based on translation
file or utf-8).


.. code-block:: perl

     my $Charset = $LanguageObject->GetRecommendedCharset();



GetPossibleCharsets()
=====================


Returns an array of possible charsets (based on translation file).


.. code-block:: perl

     my @Charsets = $LanguageObject->GetPossibleCharsets();



Time()
======


Returns a time string in language format (based on translation file).


.. code-block:: perl

     $Time = $LanguageObject->Time(
         Action => 'GET',
         Format => 'DateFormat',
     );
 
     $TimeLong = $LanguageObject->Time(
         Action => 'GET',
         Format => 'DateFormatLong',
     );
 
     $TimeLong = $LanguageObject->Time(
         Action => 'RETURN',
         Format => 'DateFormatLong',
         Year   => 1977,
         Month  => 10,
         Day    => 27,
         Hour   => 20,
         Minute => 10,
         Second => 05,
     );


These tags are supported: %A=WeekDay;%B=LongMonth;%T=Time;%D=Day;%M=Month;%Y=Year;

Note that %A only works correctly with Action GET, it might be dropped otherwise.

Also note that it is also possible to pass HTML strings for date input:


.. code-block:: perl

     $TimeLong = $LanguageObject->Time(
         Action => 'RETURN',
         Format => 'DateInputFormatLong',
         Mode   => 'NotNumeric',
         Year   => '<input value="2014"/>',
         Month  => '<input value="1"/>',
         Day    => '<input value="10"/>',
         Hour   => '<input value="11"/>',
         Minute => '<input value="12"/>',
         Second => '<input value="13"/>',
     );


Note that %B may not work in NonNumeric mode.


LanguageChecksum()
==================


This function returns an MD5 sum that is generated from all loaded language files and their modification timestamps.
Whenever a file is changed, added or removed, this checksum will change.


GetTTTemplateTranslatableStrings()
==================================


Returns an array of translation strings from tt templates.


.. code-block:: perl

     my @TranslationStrings = $LanguageObject->GetTTTemplateTranslatableStrings(
         ModuleDirectory => "$Home/...",  # optional, translates the Znuny module in the given directory
     );


Returns:


.. code-block:: perl

     my @TranslationStrings = (
         {
             Location => "TT Template: Kernel/Output/HTML/Templates/Standard/AdminACL.tt",
             Source   => 'Actions',
         }
     );



GetJSTemplateTranslatableStrings()
==================================


Returns an array of translation strings from JS templates.


.. code-block:: perl

     my @TranslationStrings = $LanguageObject->GetJSTemplateTranslatableStrings(
         ModuleDirectory  => "$Home/...",  # optional, translates the Znuny module in the given directory
     );


Returns:


.. code-block:: perl

     my @TranslationStrings = (
         {
             Location => "JS Template: Kernel/Output/JavaScript/Templates/Standard/Agent/TicketZoom/FormDraftDeleteDialog.html.tmpl",
             Source   => 'Cancel',
         }
     );



GetPerlModuleTranslatableStrings()
==================================


Returns an array of translation strings from Perl modules mark with Translatable or Translate.


.. code-block:: perl

     my @TranslationStrings = $LanguageObject->GetPerlModuleTranslatableStrings(
         ModuleDirectory  => "$Home/...",  # optional, translates the Znuny module in the given directory
     );


Returns:


.. code-block:: perl

     my @TranslationStrings = (
         {
             Location => "Perl Module: Kernel/Modules/AdminACL.pm",
             Source   => 'This field is required',
         }
     );



GetXMLTranslatableStrings()
===========================


Returns an array of translation strings from JS templates.


.. code-block:: perl

     my @TranslationStrings = $LanguageObject->GetXMLTranslatableStrings(
         ModuleDirectory  => "$Home/...",  # optional, translates the Znuny module in the given directory
     );


Returns:


.. code-block:: perl

     my @TranslationStrings = (
         {
             Location => "XML Definition:  scripts/database/initial_insert.xml",
             Source   => 'This field is required',
         }
     );



GetJSTranslatableStrings()
==========================


Returns an array of translation strings from JS.


.. code-block:: perl

     my @TranslationStrings = $LanguageObject->GetJSTranslatableStrings(
         ModuleDirectory  => "$Home/...",  # optional, translates the Znuny module in the given directory
     );


Returns:


.. code-block:: perl

     my @TranslationStrings = (
         {
             Location => "JS File: var/httpd/htdocs/js/Core.Agent.Admin.ACL",
             Source   => 'Add all',
         }
     );



GetSysConfigTranslatableStrings()
=================================


Returns an array of translation strings from SysConfig.


.. code-block:: perl

     my @TranslationStrings = $LanguageObject->GetSysConfigTranslatableStrings();


Returns:


.. code-block:: perl

     my @TranslationStrings = (
         {
             Location => "SysConfig",
             Source   => 'Add all',
         }
     );