1Locale::TextDomain(3) User Contributed Perl DocumentationLocale::TextDomain(3)
2
3
4

NAME

6       Locale::TextDomain - Perl Interface to Uniforum Message Translation
7

SYNOPSIS

9        use Locale::TextDomain ('my-package', @locale_dirs);
10
11        use Locale::TextDomain qw (my-package);
12
13        my $translated = __"Hello World!\n";
14
15        my $alt = $__{"Hello World!\n"};
16
17        my $alt2 = $__->{"Hello World!\n"};
18
19        my @list = (N__"Hello",
20                    N__"World");
21
22        printf (__n ("one file read",
23                     "%d files read",
24                     $num_files),
25                $num_files);
26
27        print __nx ("one file read", "{num} files read", $num_files,
28                    num => $num_files);
29
30        my $translated_context = __p ("Verb, to view", "View");
31
32        printf (__np ("Files read from filesystems",
33                      "one file read",
34                      "%d files read",
35                      $num_files),
36                $num_files);
37
38        print __npx ("Files read from filesystems",
39                     "one file read",
40                     "{num} files read",
41                     $num_files,
42                     num => $num_files);
43

DESCRIPTION

45       The module Locale::TextDomain(3pm) provides a high-level interface to
46       Perl message translation.
47
48   Textdomains
49       When you request a translation for a given string, the system used in
50       libintl-perl follows a standard strategy to find a suitable message
51       catalog containing the translation: Unless you explicitely define a
52       name for the message catalog, libintl-perl will assume that your
53       catalog is called 'messages' (unless you have changed the default value
54       to something else via Locale::Messages(3pm), method textdomain()).
55
56       You might think that his default strategy leaves room for optimization
57       and you are right.  It would be a lot smarter if multiple software
58       packages, all with their individual message catalogs, could be
59       installed on one system, and it should also be possible that third-
60       party components of your software (like Perl modules) can load their
61       message catalogs, too, without interfering with yours.
62
63       The solution is clear, you have to assign a unique name to your message
64       database, and you have to specify that name at run-time.  That unique
65       name is the so-called textdomain of your software package.  The name is
66       actually arbitrary but you should follow these best-practice guidelines
67       to ensure maximum interoperability:
68
69       File System Safety
70               In practice, textdomains get mapped into file names, and you
71               should therefore make sure that the textdomain you choose is a
72               valid filename on every system that will run your software.
73
74       Case-sensitivity
75               Textdomains are always case-sensitive (i. e. 'Package' and
76               'PACKAGE' are not the same).  However, since the message
77               catalogs will be stored on file systems, that may or may not
78               distinguish case when looking up file names, you should avoid
79               potential conflicts here.
80
81       Textdomain Should Match CPAN Name
82               If your software is listed as a module on CPAN, you should
83               simply choose the name on CPAN as your textdomain.  The
84               textdomain for libintl-perl is hence 'libintl-perl'.  But
85               please replace all periods ('.') in your package name with an
86               underscore because ...
87
88       Internet Domain Names as a Fallback
89               ... if your software is not a module listed on CPAN, as a last
90               resort you should use the Java(tm) package scheme, i. e. choose
91               an internet domain that you are owner of (or ask the owner of
92               an internet domain) and concatenate your preferred textdomain
93               with the reversed internet domain.  Example: Your company runs
94               the web-site 'www.foobar.org' and is the owner of the domain
95               'foobar.org'.  The textdomain for your company's software
96               'barfoos' should hence be 'org.foobar.barfoos'.
97
98       If your software is likely to be installed in different versions on the
99       same system, it is probably a good idea to append some version
100       information to your textdomain.
101
102       Other systems are less strict with the naming scheme for textdomains
103       but the phenomena known as Perl is actually a plethora of small,
104       specialized modules and it is probably wisest to postulate some
105       namespace model in order to avoid chaos.
106
107   Binding textdomains to directories
108       Once the system knows the textdomain of the message that you want to
109       get translated into the user's language, it still has to find the
110       correct message catalog.  By default, libintl-perl will look up the
111       string in the translation database found in the directories
112       /usr/share/locale and /usr/local/share/locale (in that order).
113
114       It is neither guaranteed that these directories exist on the target
115       machine, nor can you be sure that the installation routine has write
116       access to these locations.  You can therefore instruct libintl-perl to
117       search other directories prior to the default directories.  Specifying
118       a differnt search directory is called binding a textdomain to a
119       directory.
120
121       Beginning with version 1.20, Locale::TextDomain extends the default
122       strategy by a Perl-specific approach.  If File::ShareDir is installed,
123       it will look in the subdirectories named locale and LocaleData (in that
124       order) in the directory returned by "File::ShareDir::dist_dir
125       ($textdomain)" (if File::ShareDir is installed), and check for a
126       database containing the message for your textdomain there.  This allows
127       you to install your database in the Perl-specific shared directory
128       using Module::Install's "install_share" directive or the Dist::Zilla
129       ShareDir plugin.
130
131       If File::ShareDir is not availabe, or if Locale::TextDomain fails to
132       find the translation files in the File::ShareDir directory, it will
133       next look in every directory found in the standard include path @INC,
134       and check for a database containing the message for your textdomain
135       there. Example: If the path /usr/lib/perl/5.8.0/site_perl is in your
136       @INC, you can install your translation files in
137       /usr/lib/perl/5.8.0/site_perl/LocaleData, and they will be found at
138       run-time.
139

USAGE

141       It is crucial to remember that you use Locale::TextDomain(3) as
142       specified in the section "SYNOPSIS", that means you have to use it, not
143       require it.  The module behaves quite differently compared to other
144       modules.
145
146       The most significant difference is the meaning of the list passed as an
147       argument to the use() function.  It actually works like this:
148
149           use Locale::TextDomain (TEXTDOMAIN, DIRECTORY, ...)
150
151       The first argument (the first string passed to use()) is the textdomain
152       of your package, optionally followed by a list of directories to search
153       instead of the Perl-specific directories (see above: /LocaleData
154       appended to a File::ShareDir directory and every path in @INC).
155
156       If you are the author of a package 'barfoos', you will probably put the
157       line
158
159           use Locale::TextDomain 'barfoos';
160
161       resp. for non-CPAN modules
162
163           use Locale::TextDomain 'org.foobar.barfoos';
164
165       in every module of your package that contains translatable strings. If
166       your module has been installed properly, including the message
167       catalogs, it will then be able to retrieve these translations at run-
168       time.
169
170       If you have not installed the translation database in a directory
171       LocaleData in the File::ShareDir directory or the standard include path
172       @INC (or in the system directories /usr/share/locale resp.
173       /usr/local/share/locale), you have to explicitely specify a search path
174       by giving the names of directories (as strings!) as additional
175       arguments to use():
176
177           use Locale::TextDomain qw (barfoos ./dir1 ./dir2);
178
179       Alternatively you can call the function bindtextdomain() with suitable
180       arguments (see the entry for bindtextdomain() in "FUNCTIONS" in
181       Locale::Messages).  If you do so, you should pass "undef" as an
182       additional argument in order to avoid unnecessary lookups:
183
184           use Locale::TextDomain ('barfoos', undef);
185
186       You see that the arguments given to use() have nothing to do with what
187       is imported into your namespace, but they are rather arguments to
188       textdomain(), resp. bindtextdomain().  Does that mean that
189       Locale::TextDomain exports nothing into your namespace? Umh, not
190       exactly ... in fact it imports all functions listed below into your
191       namespace, and hence you should not define conflicting functions (and
192       variables) yourself.
193
194       So, why has Locale::TextDomain to be different from other modules?  If
195       you have ever written software in C and prepared it for
196       internationalization (i18n), you will probably have defined some
197       preprocessor macros like:
198
199           #define _(String) dgettext ("my-textdomain", String)
200           #define N_(String) String
201
202       You only have to define that once in C, and the textdomain for your
203       package is automatically inserted into all gettext functions.  In Perl
204       there is no such mechanism (at least it is not portable, option -P) and
205       using the gettext functions could become quite cumbersome without some
206       extra fiddling:
207
208           print dgettext ("my-textdomain", "Hello world!\n");
209
210       This is no fun.  In C it would merely be a
211
212           printf (_("Hello world!\n"));
213
214       Perl has to be more concise and shorter than C ... see the next section
215       for how you can use Locale::TextDomain to end up in Perl with a mere
216
217           print __"Hello World!\n";
218

EXPORTED FUNCTIONS

220       All functions have quite funny names on purpose.  In fact the purpose
221       for that is quite clear: They should be short, operator-like, and they
222       should not yell for conflicts with existing functions in your
223       namespace.  You will understand it, when you internationalize your
224       first Perl program or module.  Preparing it is more like marking
225       strings as being translatable than inserting function calls.  Here we
226       go:
227
228       __ MSGID
229           NOTE: This is a double underscore!
230
231           The basic and most-used function.  It is a short-cut for a call to
232           gettext() resp. dgettext(), and simply returns the translation for
233           MSGID.  If your old code reads like this:
234
235               print "permission denied";
236
237           You will now write:
238
239               print __"permission denied";
240
241           That's all, the string will be output in the user's preferred
242           language, provided that you have installed a translation for it.
243
244           Of course you can also use parentheses:
245
246               print __("permission denied");
247
248           Or even:
249
250               print (__("permission denied"));
251
252           In my eyes, the first version without parentheses looks best.
253
254       __x MSGID, ID1 => VAL1, ID2 => VAL2, ...
255           One of the nicest features in Perl is its capability to interpolate
256           variables into strings:
257
258               print "This is the $color $thing.\n";
259
260           This nice feature might con you into thinking that you could now
261           write
262
263               print __"This is the $color $thing.\n";
264
265           Alas, that would be nice, but it is not possible.  Remember that
266           the function __() serves both as an operator for translating
267           strings and as a mark for translatable strings.  If the above
268           string would get extracted from your Perl code, the un-interpolated
269           form would end up in the message catalog because when parsing your
270           code it is unpredictable what values the variables $thing and
271           $color will have at run-time (this fact is most probably one of the
272           reasons you have written your program for).
273
274           However, at run-time, Perl will have interpolated the values
275           already before __() (resp. the underlying gettext() function) has
276           seen the original string.  Consequently something like "This is the
277           red car.\n" will be looked up in the message catalog, it will not
278           be found (because only "This is the $color $thing.\n" is included
279           in the database), and the original, untranslated string will be
280           returned.  Honestly, because this is almost always an error, the
281           xgettext(1) program will bail out with a fatal error when it comes
282           across that string in your code.
283
284           There are two workarounds for that:
285
286               printf __"This is the %s %s.\n", $color, $thing;
287
288           But that has several disadvantages: Your translator will only see
289           the isolated string, and without the surrounding code it is almost
290           impossible to interpret it correctly.  Of course, GNU emacs and
291           other software capable of editing PO translation files will allow
292           you to examine the context in the source code, but it is more
293           likely that your translator will look for a less challenging
294           translation project when she frequently comes across such messages.
295
296           And even if she does understand the underlying programming, what if
297           she has to reorder the color and the thing like in French:
298
299               msgid "This is the red car.\n";
300               msgstr "Cela est la voiture rouge.\n"
301
302           Zut alors! While it is possible to reorder the arguments to
303           printf() and friends, it requires a syntax that is is nothing that
304           you want to learn.
305
306           So what? The Perl backend to GNU gettext has defined an alternative
307           format for interpolatable strings:
308
309               "This is the {color} {thing}.\n";
310
311           Instead of Perl variables you use place-holders (legal Perl
312           variables are also legal place-holders) in curly braces, and then
313           you call
314
315               print __x ("This is the {color} {thing}.\n",
316                          thing => $thang,
317                          color => $color);
318
319           The function __x() will take the additional hash and replace all
320           occurencies of the hash keys in curly braces with the corresponding
321           values.  Simple, readable, understandable to translators, what else
322           would you want?  And if the translator forgets, misspells or
323           otherwise messes up some "variables", the msgfmt(1) program, that
324           is used to compile the textual translation file into its binary
325           representation will even choke on these errors and refuse to
326           compile the translation.
327
328       __n MSGID, MSGID_PLURAL, COUNT
329           Whew! That looks complicated ... It is best explained with an
330           example.  We'll have another look at your vintage code:
331
332               if ($files_deleted > 1) {
333                   print "All files have been deleted.\n";
334               } else {
335                   print "One file has been deleted.\n";
336               }
337
338           Your intent is clear, you wanted to avoid the cumbersome "1 files
339           deleted".  This is okay for English, but other languages have more
340           than one plural form.  For example in Russian it makes a difference
341           whether you want to say 1 file, 3 files or 6 files.  You will use
342           three different forms of the noun 'file' in each case.  [Note: Yep,
343           very smart you are, the Russian word for 'file' is in fact the
344           English word, and it is an invariable noun, but if you know that,
345           you will also understand the rest despite this little
346           simplification ...].
347
348           That is the reason for the existance of the function ngettext(),
349           that __n() is a short-cut for:
350
351               print __n"One file has been deleted.\n",
352                        "All files have been deleted.\n",
353                        $files_deleted;
354
355           Alternatively:
356
357               print __n ("One file has been deleted.\n",
358                          "All files have been deleted.\n",
359                          $files_deleted);
360
361           The effect is always the same: libintl-perl will find out which
362           plural form to pick for your user's language, and the output string
363           will always look okay.
364
365       __nx MSGID, MSGID_PLURAL, COUNT, VAR1 => VAL1, VAR2 => VAL2, ...
366           Bringing it all together:
367
368               print __nx ("One file has been deleted.\n",
369                           "{count} files have been deleted.\n",
370                           $num_files,
371                           count => $num_files);
372
373           The function __nx() picks the correct plural form (also for
374           English!)  and it is capable of interpolating variables into
375           strings.
376
377           Have a close look at the order of arguments: The first argument is
378           the string in the singular, the second one is the plural string.
379           The third one is an integer indicating the number of items.  This
380           third argument is only used to pick the correct translation.  The
381           optionally following arguments make up the hash used for
382           interpolation.  In the beginning it is often a little confusing
383           that the variable holding the number of items will usually be
384           repeated somewhere in the interpolation hash.
385
386       __xn MSGID, MSGID_PLURAL, COUNT, VAR1 => VAL1, VAR2 => VAL2, ...
387           Does exactly the same thing as __nx().  In fact it is a common typo
388           promoted to a feature.
389
390       __p MSGCTXT, MSGID
391           This is much like __. The "p" stands for "particular", and the
392           MSGCTXT is used to provide context to the translator. This may be
393           neccessary when your string is short, and could stand for multiple
394           things. For example:
395
396               print __p"Verb, to view", "View";
397               print __p"Noun, a view", "View";
398
399           The above may be "View" entries in a menu, where View->Source and
400           File->View are different forms of "View", and likely need to be
401           translated differently.
402
403           A typical usage are GUI programs.  Imagine a program with a main
404           menu and the notorious "Open" entry in the "File" menu.  Now
405           imagine, there is another menu entry Preferences->Advanced->Policy
406           where you have a choice between the alternatives "Open" and
407           "Closed".  In English, "Open" is the adequate text at both places.
408           In other languages, it is very likely that you need two different
409           translations.  Therefore, you would now write:
410
411               __p"File|", "Open";
412               __p"Preferences|Advanced|Policy", "Open";
413
414           In English, or if no translation can be found, the second argument
415           (MSGID) is returned.
416
417           This function was introduced in libintl-perl 1.17.
418
419       __px MSGCTXT, MSGID, VAR1 => VAL1, VAR2 => VAL2, ...
420           Like __p(), but supports variable substitution in the string, like
421           __x().
422
423               print __px("Verb, to view", "View {file}", file => $filename);
424
425           See __p() and __x() for more details.
426
427           This function was introduced in libintl-perl 1.17.
428
429       __np MSGCTXT, MSGID, MSGID_PLURAL, COUNT
430           This adds context to plural calls. It should not be needed very
431           often, if at all, due to the __nx() function. The type of variable
432           substitution used in other gettext libraries (using sprintf-like
433           sybols, like %s or %1) sometimes required context. For a (bad)
434           example of this:
435
436               printf (__np("[count] files have been deleted",
437                           "One file has been deleted.\n",
438                           "%s files have been deleted.\n",
439                           $num_files),
440                       $num_files);
441
442           NOTE: The above usage is discouraged. Just use the __nx() call,
443           which provides inline context via the key names.
444
445           This function was introduced in libintl-perl 1.17.
446
447       __npx MSGCTXT, MSGID, MSGID_PLURAL, COUNT, VAR1 => VAL1, VAR2 => VAL2,
448       ...
449           This is provided for comleteness. It adds the variable
450           interpolation into the string to the previous method, __np().
451
452           It's usage would be like so:
453
454               print __npx ("Files being permenantly removed",
455                            "One file has been deleted.\n",
456                            "{count} files have been deleted.\n",
457                            $num_files,
458                            count => $num_files);
459
460           I cannot think of any situations requiring this, but we can easily
461           support it, so here it is.
462
463           This function was introduced in libintl-perl 1.17.
464
465       N__(ARG1)
466           A no-op function that simply echoes its arguments to the caller.
467           Take the following piece of Perl:
468
469               my @options = (
470                   "Open",
471                   "Save",
472                   "Save As",
473               );
474
475               ...
476
477               my $option = $options[1];
478
479           Now say that you want to have this translatable.  You could
480           sometimes simply do:
481
482               my @options = (
483                   __"Open",
484                   __"Save",
485                   __"Save As",
486               );
487
488               ...
489
490               my $option = $options[1];
491
492           But often times this will not be what you want, for example when
493           you also need the unmodified original string.  Sometimes it may not
494           even work, for example, when the preferred user language is not yet
495           determined at the time that the list is initialized.
496
497           In these cases you would write:
498
499               my @options = (
500                   N__"Open",
501                   N__"Save",
502                   N__"Save As",
503               );
504
505               ...
506
507               my $option = __($options[1]);
508               # or: my $option = dgettext ('my-domain', $options[1]);
509
510           Now all the strings in @options will be left alone, since N__()
511           returns its arguments (one ore more) unmodified.  Nevertheless, the
512           string extractor will be able to recognize the strings as being
513           translatable.  And you can still get the translation later by
514           passing the variable instead of the string to one of the above
515           translation functions.
516
517       N__n (MSGID, MSGID_PLURAL, COUNT)
518           Does exactly the same as N__().  You will use this form if you have
519           to mark the strings as having plural forms.
520
521       N__p (MSGCTXT, MSGID)
522           Marks MSGID as N__() does, but in the context MSGCTXT.
523
524       N__np (MSGCTXT, MSGID, MSGID_PLURAL, COUNT)
525           Marks MSGID as N__n() does, but in the context MSGCTXT.  =back
526

EXPORTED VARIABLES

528       The module exports several variables into your namespace:
529
530       %__ A tied hash.  Its keys are your original messages, the values are
531           their translations:
532
533               my $title = "<h1>$__{'My Homepage'}</h1>";
534
535           This is much better for your translation team than
536
537               my $title = __"<h1>My Homepage</h1>";
538
539           In the second case the HTML code will make it into the translation
540           database and your translators have to be aware of HTML syntax when
541           translating strings.
542
543           Warning: Do not use this hash outside of double-quoted strings!
544           The code in the tied hash object relies on the correct working of
545           the function caller() (see "perldoc -f caller"), and this function
546           will report incorrect results if the tied hash value is the
547           argument to a function from another package, for example:
548
549             my $result = Other::Package::do_it ($__{'Some string'});
550
551           The tied hash code will see "Other::Package" as the calling
552           package, instead of your own package.  Consequently it will look up
553           the message in the wrong text domain.  There is no workaround for
554           this bug.  Therefore:
555
556           Never use the tied hash interpolated strings!
557
558       $__ A reference to "%__", in case you prefer:
559
560                my $title = "<h1>$__->{'My Homepage'}</h1>";
561

CLASS METHODS

563       The following class methods are defined:
564
565       options
566           Returns a space-separated list of all '--keyword' and all '--flag'
567           options for xgettext(1), when extracing strings from Perl source
568           files localized with Locale::TextDomain.
569
570           The option should rather be called xgettextDefaultOptions.  With
571           regard to the typical use-case, a shorter name has been picked:
572
573               xgettext `perl -MLocale::TextDomain -e 'print Locale::TextDomain->options'`
574
575           See
576           <https://www.gnu.org/software/gettext/manual/html_node/xgettext-Invocation.html>
577           for more information about the xgettext options '--keyword' and
578           '--flag'.
579
580           If you want to disable the use of the xgettext default keywords,
581           you should pass an option '--keyword=""' to xgettext before the
582           options returned by this method.
583
584           If you doubt the usefulness of this method, check the output on the
585           command-line:
586
587               perl -MLocale::TextDomain -e 'print Locale::TextDomain->options'
588
589           Nothing that you want to type yourself.
590
591           This method was added in libintl-perl 1.28.
592
593       keywords
594           Returns a space-separated list of all '--keyword' options for
595           xgettext(1) so that all translatable strings are properly
596           extracted.
597
598           This method was added in libintl-perl 1.28.
599
600       flags
601           Returns a space-separated list of all '--flag' options for
602           xgettext(1) so that extracted strings are properly flagged.
603
604           This method was added in libintl-perl 1.28.
605

PERFORMANCE

607       Message translation can be a time-consuming task.  Take this little
608       example:
609
610           1: use Locale::TextDomain ('my-domain');
611           2: use POSIX (:locale_h);
612           3:
613           4: setlocale (LC_ALL, '');
614           5: print __"Hello world!\n";
615
616       This will usually be quite fast, but in pathological cases it may run
617       for several seconds.  A worst-case scenario would be a Chinese user at
618       a terminal that understands the codeset Big5-HKSCS.  Your translator
619       for Chinese has however chosen to encode the translations in the
620       codeset EUC-TW.
621
622       What will happen at run-time?  First, the library will search and load
623       a (maybe large) message catalog for your textdomain 'my-domain'.  Then
624       it will look up the translation for "Hello world!\n", it will find that
625       it is encoded in EUC-TW.  Since that differs from the output codeset
626       Big5-HKSCS, it will first load a conversion table containing several
627       ten-thousands of codepoints for EUC-TW, then it does the same with the
628       smaller, but still very large conversion table for Big5-HKSCS, it will
629       convert the translation on the fly from EUC-TW into Big5-HKSCS, and
630       finally it will return the converted translation.
631
632       A worst-case scenario but realistic.  And for these five lines of
633       codes, there is not much you can do to make it any faster.  You should
634       understand, however, when the different steps will take place, so that
635       you can arrange your code for it.
636
637       You have learned in the section "DESCRIPTION" that line 1 is
638       responsible for locating your message database.  However, the use()
639       will do nothing more than remembering your settings.  It will not
640       search any directories, it will not load any catalogs or conversion
641       tables.
642
643       Somewhere in your code you will always have a call to
644       POSIX::setlocale(), and the performance of this call may be time-
645       consuming, depending on the architecture of your system.  On some
646       systems, this will consume very little time, on others it will only
647       consume a considerable amount of time for the first call, and on others
648       it may always be time-consuming.  Since you cannot know, how
649       setlocale() is implemented on the target system, you should reduce the
650       calls to setlocale() to a minimum.
651
652       Line 5 requests the translation for your string.  Only now, the library
653       will actually load the message catalog, and only now will it load
654       eventually needed conversion tables.  And from now on, all this
655       information will be cached in memory.  This strategy is used throughout
656       libintl-perl, and you may describe it as 'load-on-first-access'.
657       Getting the next translation will consume very little resources.
658
659       However, although the translation retrieval is somewhat obfuscated by
660       an operator-like function call, it is still a function call, and in
661       fact it even involves a chain of function calls.  Consequently, the
662       following example is probably bad practice:
663
664           foreach (1 .. 100_000) {
665               print __"Hello world!\n";
666           }
667
668       This example introduces a lot of overhead into your program.  Better do
669       this:
670
671           my $string = __"Hello world!\n";
672           foreach (1 .. 100_000) {
673               print $string;
674           }
675
676       The translation will never change, there is no need to retrieve it over
677       and over again.  Although libintl-perl will of course cache the
678       translation read from the file system, you can still avoid the overhead
679       for the function calls.
680

AUTHOR

682       Copyright (C) 2002-2017 Guido Flohr <http://www.guido-flohr.net/>
683       (<mailto:guido.flohr@cantanea.com>), all rights reserved.  See the
684       source code for details!code for details!
685

SEE ALSO

687       Locale::Messages(3pm), Locale::gettext_pp(3pm), perl(1), gettext(1),
688       gettext(3)
689

POD ERRORS

691       Hey! The above document had some coding errors, which are explained
692       below:
693
694       Around line 982:
695           You forgot a '=back' before '=head1'
696
697       Around line 1175:
698           =cut found outside a pod block.  Skipping to next block.
699
700
701
702perl v5.34.0                      2022-01-21             Locale::TextDomain(3)
Impressum