CGI::FormMagick::L10N

	Skill level: Developer
	Risk of inconsistencies with Koozali SME Server methodology, upgrades & functionality is high. One must be knowledgeable about how changes impact their Koozali SME Server. Significant risk of irreversible harm.

NAME

CGI::FormMagick::L10N - localization routines for FormMagick

In a root terminal you can do the command below if you want to display the up-to-date content

perldoc CGI::FormMagick

SYNOPSIS

        use CGI::FormMagick::L10N;

DESCRIPTION

L10N (Localisation) is the name given to the process of providing translations into another language. The previous step to this is I18N (internationalisation) which is the process of making an application ready to accept the translations.

We’ve done the work of I18N for you, so all you have to do is provide translations for your apps. This is done using the <lexicon> XML element, like so:

          <form>
              ...
          </form>

          <lexicon lang="fr">
              <entry>
                  <base>Hello</base>
                  <trans>Bonjour</trans>
              </entry>
          </lexicon>

Sometimes you need to substitute variables into the localised strings. There are three ways to do this:

1. Substitute another lexicon entry by it’s base name. This substitution will happen automagically:

          <lexicon lang="fr">
              <entry>
                  <base>This text includes a {$var}.</base>
                  <trans>A {$var} this text includes.</trans>
              </entry>
              <entry>
                  <base>var</base>
                  <trans>variable</trans>
              </entry>
          </lexicon>

2. Use a custom method in your FormMagick subclass that returns a hash of variables for substitution. This substitution will happen automagically if you use the ’params’ attribute of the lexicon XML element, and define the named method in your FormMagick subclass:

          <lexicon lang="fr" params="getLexiconParams()">
              <entry>
                  <base>This text includes a {$var}.</base>
                  <trans>A {$var} this text includes.</trans>
              </entry>
          </lexicon>
 
          package MyFormMagick;
          our @ISA = (’CGI::FormMagick’);
          sub getLexiconParams
          {
              return (var => "variable");
          }
          1;

3. Pass a hashref to the localise() method. This substitution will happen automagically if you pass the hashref as an additional parameter to the localise() method:

          <lexicon lang="fr">
              <entry>
                  <base>This text includes a {$var}.</base>
                  <trans>A {$var} this text includes.</trans>
              </entry>
          </lexicon>
 
          ...
          my $text = ’This text includes a {$var}.’;
          my $translated = $fm->localise($text, {var => ’variable’});
          ...

Localisation preferences are picked up from the HTTP_ACCEPT_LANGUAGE environment variable passed by the user’s browser. In Netscape, you set this by choosing "Edit, Preferences, Navigator, Languages" and then choosing your preferred language.

Localisation is performed on:

• Form titles

• Page titles and descriptions

• Field labels and descriptions

• Validation error messages

If you wish to localise other textual information such as your HTML Templates, you will have to explicitly call the l10n routines.

USER METHODS

localise($string)

Translates a string into the end-user’s preferred language by checking their HTTP_ACCEPT_LANG variable and looking up a lexicon hash for that language (if it exists). If no translation can be found, returns the original string untranslated. Takes the text to translate as the first argument, and optionally, a hashref of variables for substitution as the second argument. WARNING WARNING WARNING: The internals of this routine will change significantly in version 0.60, when we remove Locale::Maketext from the equation. However, its output should still be the same. Just FYI.

check_l10n()

print out lexicons to check whether they’re what you think they are this is mostly for debugging purposes. If you have DEBUG set to 1 in your call to the new() method, you’ll see a link at the bottom of each page that says "Check L10N". This is the subroutine that’s called when you follow that link.

get_lexicon()

Attempts to find a suitable localisation lexicon for use, and returns it as a hash.

_set_lexicon_params(@lexicons)

Given a hash ref of lexicon attributes, find the ’params’ attribute containing a method that returns a params hash (if set), and save it as an object attribute.

_get_lexicon_params()

Return the merged params hash for the preferred lexicon.

clean_lexicon(@lexicons)

Given an array of messy lexicons, cleans them up into a nice neat hash of base/translation pairs.

It’s an array because you might have more than one lexicon for the same langauge. These get merged into one lexicon hash, so that the first lexicon of a given language will be overridden by the second.

get_languages()

Picks up the preferred language(s) from $ENV{HTTP_ACCEPT_LANGUAGE}. Figures out super-languages (eg "en" is a super-language of "en-US") and pushes them onto the list, along with the fallback language specified by $fm->fallback_language() (if any). Smashes them all to lowercase before returning them.

SEE ALSO

The general documentation for FormMagick ("perldoc CGI::FormMagick")

More information about FormMagick may be found at http://sourceforge.net/projects/formmagick/

      CGI::FormMagick