NAME

Krang::Localization - Krang localization module

SYNOPSIS

   use Krang::ClassLoader Localization => qw(localize);
   $localized_string = localize('some string');

   # All AvailableLanguages set in conf/krang.conf are available via
   # the exported %LANG hash, with keys being arbitrary language tags
   # and values being the corresponding language names.
   my $lang = $LANG{en}; # yields 'English';

   # install a localization distribution
   pkg('Localization')->install(src => '/path/to/Krang-Localization-Deutsch-3.01.tar.gz');

   # uninstall a localization distribution
   pkg('Localization')->uninstall(lang => de);

DESCRIPTION

This module provides localization to Krang by exporting the functions localize() and localize_template(). The latter is primarily used in lang/bin/krang_localize_templates to pre-compile localized templates. For this to work, wrap any static template strings in

   <tmpl_lang SomeSTRING>

tags.

Lexicons are Krang::ConfigApacheFormat objects accessible through the class method

  pkg('Localization')->get_lexicon($language_tag);

Direct access to lexicons should be rarely necessary. Use the exported localize() function instead which honors the logged in user's language preference.

INTERFACE

• localize('Edit')
  
This exported method returns the localized version of its argument according to the user's language reference. It returns its argument unchanged if no lexicon entry is found or if the language is set to English. For German, a lexicon entry may be

    "Edit Story"               "Story bearbeiten"

• localize('WEEKDAYS')
  
Returns a localized list of weekday names according to the user's language setting. For French, the lexicon entry should read

    "Weekdays"   Dim Lun Mar Mer Jeu Ven Sam

• localize('This is number %s', $number)
  
Additional strings may be interpolated into the localized string using sprintf()'s '%s' placeholder. The Turkish lexicon entry for the above mentioned example would be

    "This is number %s"  "Bu sayi %s"

• localize_template($textref, $language)
  
All strings in $textref wrapped in <tmpl_lang> tags are localized for the language indicated by $language_tag. $textref should contain a reference to a string containing a template, $language_tag is supposed to be a valid RFC3066-style tag representing a valid entry into the %L10N lexicon hash.

There are 2 syntax flavors for <tmpl_lang> tags. The 1st is just a simple

    <tmpl_lang String to be translated>

Where everything inside is translated as-is. The 2nd is more complicated to deal with situations where there are words to be substituted into the the translation that don't need translation, but the rest of the sentence does. Something like

    <tmpl_lang "Your username is %s", username>

Which will get translated and rendered into something like this (example in Spanish)

    Su Nombre de Usuario es <tmpl_var username escape=html>

If $ENV{KRANG_RECORD_MISSING_LOCALIZATIONS} is set to true, then any strings which do not have corresponding translations will be collected in the %Krang::Localization::MISSING hash (which is exportable).

• pkg('Localization')->get_lexicon($language)
  
Returns a Krang::ConfigApacheFormat object representing a lexicon mapping English to the language indicated the methods argument.

Croaks if no lexicon for the given language is found in the package hash %L10N.

• pkg('Localization')->install(src => $path, verbose => 1, downgrade => 1, version => $version)
  
Install a localization package. The src argument must contain the path to an localization tarball produced by lang/bin/krang_lang_dist and readable by KrangUser.

The verbose option will cause install steps to be logged to STDERR. The downgrade option will allow to install a localization package whose version is lower than $Krang::VERSION. You have to specify the version option for this to work.

• pkg('Localization')->uninstall(lang => LANGUAGE_TAG, verbose => 1)
  
Uninstall a localization distribution. The lang argument must be a RFC3066-style language tag representing a localization's root directory below lang/. The verbose option will cause uninstall steps to be logged to STDERR.