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_template($textref, $language_tag)
  
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.
• debug_localize_template($textref, $language)
  
This method is only useful for debugging and testing. It's used when calling lang/bin/krang_localize_templates with the --print_missing option to find strings in templates whose localization is missing in the lexicon indicated by $language.

This method is triggered if $ENV{KRANG_RECORD_MISSING_LOCALIZATIONS} is set to a true value.

• 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.