1Locale::TextDomain(3) User Contributed Perl DocumentationLocale::TextDomain(3)
2
6 Locale::TextDomain - Perl Interface to Uniforum Message Translation
7
9 use Locale::TextDomain ('my-package', @locale_dirs);
10 use Locale::TextDomain qw (my-package);
12 my $translated = __"Hello World!\n";
14 my $alt = $__{"Hello World!\n"};
16 my $alt2 = $__->{"Hello World!\n"};
18 my @list = (N__"Hello",
20 N__"World");
21 printf (__n ("one file read",
23 "%d files read",
24 $num_files),
25 $num_files);
26 print __nx ("one file read", "{num} files read", $num_files,
28 num => $num_files);
29 my $translated_context = __p ("Verb, to view", "View");
31 printf (__np ("Files read from filesystems",
33 "one file read",
34 "%d files read",
35 $num_files),
36 $num_files);
37 print __npx ("Files read from filesystems",
39 "one file read",
40 "{num} files read",
41 $num_files,
42 num => $num_files);
43
45 The module Locale::TextDomain(3pm) provides a high-level interface to
46 Perl message translation.
47 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 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 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 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 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 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 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 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 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 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 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 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 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
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 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 use Locale::TextDomain (TEXTDOMAIN, DIRECTORY, ...)
150 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 If you are the author of a package 'barfoos', you will probably put the
157 line
158 use Locale::TextDomain 'barfoos';
160 resp. for non-CPAN modules
162 use Locale::TextDomain 'org.foobar.barfoos';
164 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 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 use Locale::TextDomain qw (barfoos ./dir1 ./dir2);
178 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 use Locale::TextDomain ('barfoos', undef);
185 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 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 #define _(String) dgettext ("my-textdomain", String)
200 #define N_(String) String
201 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 print dgettext ("my-textdomain", "Hello world!\n");
209 This is no fun. In C it would merely be a
211 printf (_("Hello world!\n"));
213 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 print __"Hello World!\n";
218
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 __ MSGID
229 NOTE: This is a double underscore!
230 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 print "permission denied";
236 You will now write:
238 print __"permission denied";
240 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 Of course you can also use parentheses:
245 print __("permission denied");
247 Or even:
249 print (__("permission denied"));
251 In my eyes, the first version without parentheses looks best.
253 __x MSGID, ID1 => VAL1, ID2 => VAL2, ...
255 One of the nicest features in Perl is its capability to interpolate
256 variables into strings:
257 print "This is the $color $thing.\n";
259 This nice feature might con you into thinking that you could now
261 write
262 print __"This is the $color $thing.\n";
264 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 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 There are two workarounds for that:
285 printf __"This is the %s %s.\n", $color, $thing;
287 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 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 msgid "This is the red car.\n";
300 msgstr "Cela est la voiture rouge.\n"
301 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 So what? The Perl backend to GNU gettext has defined an alternative
307 format for interpolatable strings:
308 "This is the {color} {thing}.\n";
310 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 print __x ("This is the {color} {thing}.\n",
316 thing => $thang,
317 color => $color);
318 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 __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 if ($files_deleted > 1) {
333 print "All files have been deleted.\n";
334 } else {
335 print "One file has been deleted.\n";
336 }
337 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 That is the reason for the existance of the function ngettext(),
349 that __n() is a short-cut for:
350 print __n"One file has been deleted.\n",
352 "All files have been deleted.\n",
353 $files_deleted;
354 Alternatively:
356 print __n ("One file has been deleted.\n",
358 "All files have been deleted.\n",
359 $files_deleted);
360 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 __nx MSGID, MSGID_PLURAL, COUNT, VAR1 => VAL1, VAR2 => VAL2, ...
366 Bringing it all together:
367 print __nx ("One file has been deleted.\n",
369 "{count} files have been deleted.\n",
370 $num_files,
371 count => $num_files);
372 The function __nx() picks the correct plural form (also for
374 English!) and it is capable of interpolating variables into
375 strings.
376 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 __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 __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 print __p"Verb, to view", "View";
397 print __p"Noun, a view", "View";
398 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 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 __p"File|", "Open";
412 __p"Preferences|Advanced|Policy", "Open";
413 In English, or if no translation can be found, the second argument
415 (MSGID) is returned.
416 This function was introduced in libintl-perl 1.17.
418 __px MSGCTXT, MSGID, VAR1 => VAL1, VAR2 => VAL2, ...
420 Like __p(), but supports variable substitution in the string, like
421 __x().
422 print __px("Verb, to view", "View {file}", file => $filename);
424 See __p() and __x() for more details.
426 This function was introduced in libintl-perl 1.17.
428 __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 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 NOTE: The above usage is discouraged. Just use the __nx() call,
443 which provides inline context via the key names.
444 This function was introduced in libintl-perl 1.17.
446 __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 It's usage would be like so:
453 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 I cannot think of any situations requiring this, but we can easily
461 support it, so here it is.
462 This function was introduced in libintl-perl 1.17.
464 N__(ARG1)
466 A no-op function that simply echoes its arguments to the caller.
467 Take the following piece of Perl:
468 my @options = (
470 "Open",
471 "Save",
472 "Save As",
473 );
474 ...
476 my $option = $options[1];
478 Now say that you want to have this translatable. You could
480 sometimes simply do:
481 my @options = (
483 __"Open",
484 __"Save",
485 __"Save As",
486 );
487 ...
489 my $option = $options[1];
491 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 In these cases you would write:
498 my @options = (
500 N__"Open",
501 N__"Save",
502 N__"Save As",
503 );
504 ...
506 my $option = __($options[1]);
508 # or: my $option = dgettext ('my-domain', $options[1]);
509 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 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 N__p (MSGCTXT, MSGID)
522 Marks MSGID as N__() does, but in the context MSGCTXT.
523 N__np (MSGCTXT, MSGID, MSGID_PLURAL, COUNT)
525 Marks MSGID as N__n() does, but in the context MSGCTXT. =back
526
528 The module exports several variables into your namespace:
529 %__ A tied hash. Its keys are your original messages, the values are
531 their translations:
532 my $title = "<h1>$__{'My Homepage'}</h1>";
534 This is much better for your translation team than
536 my $title = __"<h1>My Homepage</h1>";
538 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 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 my $result = Other::Package::do_it ($__{'Some string'});
550 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 Never use the tied hash interpolated strings!
557 $__ A reference to "%__", in case you prefer:
559 my $title = "<h1>$__->{'My Homepage'}</h1>";
561
563 The following class methods are defined:
564 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 The option should rather be called xgettextDefaultOptions. With
571 regard to the typical use-case, a shorter name has been picked:
572 xgettext `perl -MLocale::TextDomain -e 'print Locale::TextDomain->options'`
574 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 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 If you doubt the usefulness of this method, check the output on the
585 command-line:
586 perl -MLocale::TextDomain -e 'print Locale::TextDomain->options'
588 Nothing that you want to type yourself.
590 This method was added in libintl-perl 1.28.
592 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 This method was added in libintl-perl 1.28.
599 flags
601 Returns a space-separated list of all '--flag' options for
602 xgettext(1) so that extracted strings are properly flagged.
603 This method was added in libintl-perl 1.28.
605
607 Message translation can be a time-consuming task. Take this little
608 example:
609 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 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 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 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 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 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 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 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 foreach (1 .. 100_000) {
665 print __"Hello world!\n";
666 }
667 This example introduces a lot of overhead into your program. Better do
669 this:
670 my $string = __"Hello world!\n";
672 foreach (1 .. 100_000) {
673 print $string;
674 }
675 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
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
687 Locale::Messages(3pm), Locale::gettext_pp(3pm), perl(1), gettext(1),
688 gettext(3)
689
691 Hey! The above document had some coding errors, which are explained
692 below:
693 Around line 982:
695 You forgot a '=back' before '=head1'
696 Around line 1175:
698 =cut found outside a pod block. Skipping to next block.
699perl v5.26.3 2019-05-14 Locale::TextDomain(3)