Locale::TextDomain 1.16

Locale::TextDomain is a Perl Interface to Uniforum Message Translation. SYNOPSIS use Locale::TextDomain (my-package, @locale_dirs); use Locale::TextDomain qw (my-package); my $translated = __"Hello World!n"; my $alt = $__{"Hello World!n"}; my $alt2 = $__->{"Hello World!n"}; my @list = (N__"Hello", N__"World"); my @plurals = (N__ ("One world", "{num} worlds"), N__ ("1 file", "%d files")); my $question = __x ("Error reading file {file}: {err}", file => $file, err => $!); printf (__n ("one file read", "%d files read", $num_files), $num_files); print __nx ("one file read", "{num} files read", $num_files, num => $num_files); The module Locale::TextDomain(3pm) provides a high-level interface to Perl message translation. Textdomains When your request a translation for a given string, the system used in libintl-perl follows a standard strategy to find a suitable message catalog containing the translation: Unless you explicitely define a name for the message catalog, libintl-perl will assume that your catalog is called messages (unless you have changed the default value to something else via Locale::Messages(3pm), method textdomain()). You might think that his default strategy leaves room for optimization and you are right. It would be a lot smarter if multiple software packages, all with their individual message catalogs, could be installed on one system, and it should also be possible that third-party components of your software (like Perl modules) can load their message catalogs, too, without interfering with yours. The solution is clear, you have to assign a unique name to your message database, and you have to specify that name at run-time. That unique name is the so-called textdomain of your software package. The name is actually arbitrary but you should follow these best-practice guidelines to ensure maximum interoperability: File System Safety In practice, textdomains get mapped into file names, and you should therefore make sure that the textdomain you choose is a valid filename on every system that will run your software. Case-sensitivity Textdomains are always case-sensitive (i. e. Package and PACKAGE are not the same). However, since the message catalogs will be stored on file systems, that may or may not distinguish case when looking up file names, you should avoid potential conflicts here. Textdomain Should Match CPAN Name If your software is listed as a module on CPAN, you should simply choose the name on CPANS as your textdomain. The textdomain for libintl-perl is hence libintl-perl. But please replace all periods (.) in your package name with an underscore because ... Internet Domain Names as a Fallback ... if your software is not a module listed on CPAN, as a last resort you should use the Java(tm) package scheme, i. e. choose an internet domain that you are owner of (or ask the owner of an internet domain) and concatenate your preferred textdomain with the reversed internet domain. Example: Your company runs the web-site www.foobar.org and is the owner of the domain foobar.org. The textdomain for your companys software barfoos should hence be org.foobar.barfoos. If your software is likely to be installed in different versions on the same system, it is probably a good idea to append some version information to your textdomain. Other systems are less strict with the naming scheme for textdomains but the phenomena known as Perl is actually a plethora of small, specialized modules and it is probably wisest to postulate some namespace model in order to avoid chaos. Binding textdomains to directories Once the system knows the textdomain of the message that you want to get translated into the users language, it still has to find the correct message catalog. By default, libintl-perl will look up the string in the translation database found in the directories /usr/share/locale and /usr/local/share/locale (in that order). It is neither guaranteed that these directories exist on the target machine, nor can you be sure that the installation routine has write access to these locations. You can therefore instruct libintl-perl to search other directories prior to the default directories. Specifying a differnt search directory is called binding a textdomain to a directory. Locale::TextDomain extends the default strategy by a Perl specific approach. Unless told otherwise, it will look for a directory LocaleData in every component found in the standard include path @INC and check for a database containing the message for your textdomain there. Example: If the path /usr/lib/perl/5.8.0/site_perl is in your @INC, you can install your translation files in /usr/lib/perl/5.8.0/site_perl/LocaleData, and they will be found at run-time..

Requirements:	No special requirements
Platforms:	Linux
Keyword:	Cpan,  File,  Hello World,  Internet Domain,  Libraries,  Localetextdomain,  Message,  Name,  Perl,  Perl Interface,  Perl Interface Uniforum Message Translation,  Software,  Textdomain
Users rating:	0/10