NAME
PApp::I18n - internationalisation support for PApp
SYNOPSIS
use PApp::I18n;
# nothing exported by default
my $translator = PApp::I18n::open_translator("/libdir/i18n/myapp", "de");
my $table = $translator->get_table("uk,de,en"); # will return de translator
print $table->gettext("yeah"); # better define __ and N_ functionsDESCRIPTION
This module provides basic translation services, .po-reader and writer support and text and database scanners to identify tagged strings.
Anatomy of a Language/Locale ID
A "language" can be designated by either a free-form-string (that doesn't match the following formal definition) or a language-region code that must match the following regex:
/^ ([a-z][a-z][a-z]?) (?:[-_] ([a-z][a-z][a-z]?))? (?:\.(\S+))? $/ix
^ ^ ^ ^
"two or three letter code"
"optionally followed by"
"- or _ as seperator"
"two or three letter code"
"optionally followed by"
". as seperator"
"character encoding"There is no charset indicator, as only utf-8 is supported currently. The first part must be a two or three letter code from iso639-2/t (alpha2 or alpha3), optionally followed by the two or three letter country/region code from iso3166-1 and -2. Numeric region codes might be supported one day.
- set_base $path
-
Set the default i18n directory to
$path. This must be done before any calls totranslate_langidor when using relative i18n paths. - normalize_langid $langid
-
Normalize the language and country id into it's three-letter form, if possible. This requires a grep through a few kb of text but the result is cached. The special language code "*" is translated to "mul".
- translate_langid $langid[, $langid]
-
Decode the first
langidinto a description of itself and translate it into the language specified by the secondlangid(the latter does not work yet). The result of this function is being cached. - locale_charsets $locale
-
Returns a list of character sets that might be good to use for this locale. This definition is neccessarily imprecise.
The charsets returned should be considered to be in priority order, i.e. the first charset is the best. The intention of this function is to provide a list of character sets to try when outputting html text (you can output any html text in any encoding supporting html's active characters, so this is indeed a matter of taste).
If the locale contains a character set it will be the first in the returned list. The other charsets are taken from a list (see the source of this module for details).
Here are some examples of what you might expect:
de => iso-8859-1 iso-8859-15 cp1252 utf-8 rus_ukr => koi8-u iso-8859-5 cp1251 iso-ir-111 cp866 koi8-r iso-8859-5 cp1251 iso-ir-111 cp866 koi8-u utf-8 ja_JP.UTF-8 => utf-8 euc-jp sjis iso-2022-jp jis7 utf-8This function can be slow and does NOT cache any results.
Translation Support
- open_translator $path, lang1, lang2....
-
Open an existing translation directory. A translation directory can contain any number of language translation tables with filenames of the form "language.dpo". Since the translator cannot guess in which language the source has been written you have to specify this by adding additional language names.
- $translator->langs
-
Return all languages supported by this translator (in normalized form). Can be used to create language-selectors, for example.
- $table = $translator->get_table($languages)
-
Find and return a translator table for the language that best matches the
$languages. This function always succeeds by returning a dummy trable if no (physical) table can be found. This function is very fast in the general case. - $translation = $table->gettext($msgid)
-
Find the translation for $msgid, or return the original string if no translation is found. If the msgid starts with the two characters "\" and "{", then these characters and all remaining characters until the closing '}' are skipped before attempting a translation. If you do want to include these two characters at the beginning of the string, use the sequence "\{\{". This can be used to specify additional arguments to some translation steps (like the language used). Here are some examples:
string => translation \{\string => \translation \{\{string => \{translation \{}string => translationTo ensure that the string is translated "as is" just prefix it with "\{}".
- $lang = $table->lang
-
Return the language this translation table contains.
- flush_cache
-
Flush the translation table cache. This is rarely necessary, translation hash files are not written to. This can be used to ensure that new calls to
get_tableget the updated tables instead of already opened ones.
Scanning Support
As of yet undocumented
- \%trans = fuzzy_translation $string, [$domain]
-
Try to find a translation for the given string in the given domain (or globally) by finding the most similar string already in the database and return its translation(s).
- scan_init $domain
- scan_str $prefix, $string, $lang
- scan_file
- scan_field $dsn, $field, $style, $lang
- scan_end
- export_dpo $domain, $path, [$userid, $groupid, $attr]
-
Export translation domain
$domainin binary hash format to directory$path, creating it if necessary.
PO Reading and Writing
CLASS PApp::I18n::PO_Reader
This class can be used to read serially through a .po file. (where "po file" is about the same thing as a standard "Portable Object" file from the NLS standard developed by Uniforum).
- $po = new PApp::I18n::PO_Reader $pathname
-
Opens the given file for reading.
- ($msgid, $msgstr, @comments) = $po->next;
-
Read the next entry. Returns nothing on end-of-file.
CLASS PApp::I18n::PO_Writer
This class can be used to write a new .po file. (where "po file" is about the same thing as a standard "Portable Object" file from the NLS standard developed by Uniforum).
- $po = new PApp::I18n::PO_Writer $pathname
-
Opens the given file for writing.
- $po->add ($msgid, $msgstr, @comments);
-
Write another entry to the po file. See PO_Reader's
nextmethod.
AUTHOR
Marc Lehmann <schmorp@schmorp.de>
http://home.schmorp.de/