NAME
Kernel::Language – global language interface
DESCRIPTION
All language functions.
PUBLIC INTERFACE
new()
create a language object. Do not use it directly, instead use:
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.
Translate()
translate a text with placeholders.
my $Text = $LanguageObject->Translate('Hello %s!', 'world');FormatTimeString()
formats a timestamp according to the specified date format for the current language (locale).
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
0, # optional, forces the method to add the timezone info if possible
);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.
Time()
Returns a time string in language format (based on translation file).
$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:
$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.
LanguageStats()
This method is auto-generated by Dev::Tools::TranslationsUpdate.
HumanReadableDataSize()
Produces human readable data size.
my $SizeStr = $LanguageObject->HumanReadableDataSize(
Size => 123, # size in bytes
);Returns
$SizeStr = '123 B'; # example with decimal point: 123.4 MBNumberToLocaleString()
converts provided number to the localized string (thousand and decimal separators), based on the user language. Avoid usage of this method for the data that is returned to the frontend, since it's localized there. Still, it's needed for some places, like Template generator.
my $LocaleString = $LanguageObject->NumberToLocaleString(
Number => '1234.5',
MinimumDecimalPlaces => 2, (optional) minimum number of desired decimal places (default 2)
MaximumDecimalPlaces => 2, (optional) maximum number of desired decimal places (default 2)
);Returns
$LocaleString = '1,234.50';AddCustomTranslation()
Add a new custom translation.
my $Translation = $LanguageObject->AddCustomTranslation(
Language => 'pt' # required
Text => 'elephant' # required
Translation => 'elefante' # required
UserID => 1 # required
);Returns
undef - in case any error occurs
hash - {
ID => 12345,
StringID => 45678,
Language => 'pt'
Text => 'elephant',
TextHash => 'f87ee5ffc8e4828e...',
Translation => 'elefante',
CreateTime => '2024-04-19 14:19:06',
CreateBy => 1,
ChangeTime => '2024-04-19 14:19:06',
ChangeBy => 1,
}UpdateCustomTranslation()
Updates the custom translation.
my $Result = $LanguageObject->UpdateCustomTranslation(
ID => 12345 # required
Translation => 'Elefante' # required
UserID => 2 # required
);Returns
undef - in case any error occurs
1 - delete was successfullDeleteCustomTranslation()
Deletes the custom translation.
my $Result = $LanguageObject->DeleteCustomTranslation(
ID => '...' # required
);Returns
undef - in case any error occurs
1 - delete was successfullGetCustomTranslation()
Returns the custom translation.
my $Translation = $LanguageObject->GetCustomTranslation(
ID => '...' # required
);Returns
undef - in case any error occurs or the ID does not exist
hash - {
ID => 12345,
StringID => 45678,
Language => 'pt',
Text => 'elephant',
TextHash => 'f87ee5ffc8e4828e...',
Translation => 'Elefante',
CreateTime => '2024-04-19 14:19:06',
CreateBy => 1,
ChangeTime => '2024-04-19 14:29:06',
ChangeBy => 2,
}GetCustomTranslations()
Returns the custom translations.
my $Translations = $LanguageObject->GetCustomTranslations();Returns
undef - in case any error occurs
hash - {
key1 => 'value 1',
key2 => 'value 2',
...
}ListTranslations()
Returns the list of translations.
my $List = $LanguageObject->ListTranslations(
FilterOnlyCustomised => 'on' # optional
);Returns
undef - in case an error occurs
array - [
{
CustomTranslationID => '...',
Text => '...',
TextHash => '...',
Translation => '...',
CustomTranslation => '...',
CreateBy => '...',
CreateTime => '...',
ChangeTime => '...',
ChangeBy => '...',
IsBuiltIn => '...',
},
...
]SearchTranslations()
Returns the list of translations matching the given Search String. The search is case insensitive. If Page and Pagesize are provided the response will be paginated accordingly. The Search will consider the fields Text, Translation and CustomTranslation.
my $List = $LanguageObject->SearchTranslations(
Page => 1, # optional
Pagesize => 50, # optional
Search => 'elephant', # required, the string to search for
FilterOnlyCustomised => 'on' # optional
);Returns
array - [
{
CustomTranslationID => '...',
Text => '...',
TextHash => '...',
Translation => '...',
CustomTranslation => '...',
CreateBy => '...',
CreateTime => '...',
ChangeTime => '...',
ChangeBy => '...',
IsBuiltIn => '...',
},
{
...
},
...
]CountTranslations()
Returns the number of translations available.
my $Count = $LanguageObject->CountTranslations();GetTranslations()
Returns the built-in translations merged with the custom ones.
my $Translations = $LanguageObject->GetTranslations();Returns
{
key1 => 'value 1',
key2 => 'value 2',
...
}GetBuiltInTranslations()
Returns the built-in translations.
my $Translations = $LanguageObject->GetBuiltInTranslations();Returns
{
key1 => 'value 1',
key2 => 'value 2',
...
}Code()
Returns the language code.
my $Code = $LanguageObject->Code();Name()
Returns the language name.
my $Name = $LanguageObject->Name();NativeName()
Returns the language native name.
my $NativeName = $LanguageObject->NativeName();AvailableLanguages()
Returns an array of the available languages.
my $ArrayRef = $LanguageObject->AvailableLanguages();Returns
[
{
Code => 'pt',
Name => 'Portuguese',
NativeName => 'Portugues',
},
]CacheType()
Returns the cache type name.
my $CacheType = $LanguageObject->CacheType();IsValidLanguage
Check if the given language code is valid/recognized by the system.
my $Valid = $LanguageObject->IsValidLanguage(
Code => '...' # required
);Returns
1 - valid language code
0 - invalid language codeGenerateTextHash()
Generates a sha256 hash of the text.
my $Hash = $LanguageObject->GenerateTextHash( Text => '...' );