1Locale::Messages(3) User Contributed Perl Documentation Locale::Messages(3)
2
6 Locale::Messages - Gettext Like Message Retrieval
7
9 use Locale::Messages qw(:locale_h :libintl_h);
10 gettext $msgid;
12 dgettext $textdomain, $msgid;
13 dcgettext $textdomain, $msgid, LC_MESSAGES;
14 ngettext $msgid, $msgid_plural, $count;
15 dngettext $textdomain, $msgid, $msgid_plural, $count;
16 dcngettext $textdomain, $msgid, $msgid_plural, $count, LC_MESSAGES;
17 pgettext $msgctxt, $msgid;
18 dpgettext $textdomain, $msgctxt, $msgid;
19 dcpgettext $textdomain, $msgctxt, $msgid, LC_MESSAGES;
20 npgettext $msgctxt, $msgid, $msgid_plural, $count;
21 dnpgettext $textdomain, $msgctxt, $msgid, $msgid_plural, $count;
22 dcnpgettext $textdomain, $msgctxt, $msgid, $msgid_plural, $count, LC_MESSAGES;
23 textdomain $textdomain;
24 bindtextdomain $textdomain, $directory;
25 bind_textdomain_codeset $textdomain, $encoding;
26 bind_textdomain_filter $textdomain, \&filter, $data;
27 turn_utf_8_on ($variable);
28 turn_utf_8_off ($variable);
29 nl_putenv ('OUTPUT_CHARSET=koi8-r');
30 my $category = LC_CTYPE;
31 my $category = LC_NUMERIC;
32 my $category = LC_TIME;
33 my $category = LC_COLLATE;
34 my $category = LC_MONETARY;
35 my $category = LC_MESSAGES;
36 my $category = LC_ALL;
37
39 The module Locale::Messages is a wrapper around the interface to
40 message translation according to the Uniforum approach that is for
41 example used in GNU gettext and Sun's Solaris. It is intended to allow
42 Locale::Messages(3) to switch between different implementations of the
43 lower level libraries but this is not yet implemented.
44 Normally you should not use this module directly, but the high level
46 interface Locale::TextDomain(3) that provides a much simpler interface.
47 This description is therefore deliberately kept brief. Please refer to
48 the GNU gettext documentation available at
49 <http://www.gnu.org/manual/gettext/> for in-depth and background
50 information on the topic.
51 The lower level module Locale::gettext_pp(3) provides the Perl
53 implementation of gettext() and related functions.
54
56 The module exports by default nothing. Every function has to be
57 imported explicitely or via an export tag ("EXPORT TAGS").
58 gettext MSGID
60 Returns the translation for MSGID. Example:
61 print gettext "Hello World!\n";
63 If no translation can be found, the unmodified MSGID is returned,
65 i. e. the function can never fail, and will never mess up your
66 original message.
67 Note for Perl 5.6 and later: The returned string will always have
69 the UTF-8 flag off by default. See the documentation for function
70 bind_textdomain_filter() for a way to change this behavior.
71 One common mistake is this:
73 print gettext "Hello $name!";
75 Perl will interpolate the variable $name before the function will
77 see the string. Unless the corresponding message catalog contains
78 a message "Hello Tom!", "Hello Dick!" or "Hello Harry!", no
79 translation will be found.
80 Using printf() and friends has its own problems:
82 print sprintf (gettext ("This is the %s %s."), $color, $thing);
84 (The example is stupid because neither color nor thing will get
86 translated here ...).
87 In English the adjective (the color) will precede the noun, many
89 other languages (for example French or Italian) differ here. The
90 translator of the message may therefore have a hard time to find a
91 translation that will still work and not sound stupid in the target
92 language. Many C implementations of printf() allow to change the
93 order of the arguments, and a French translator could then say:
94 "C'est le %2$s %1$s."
96 Perl printf() implements this feature as of version 5.8 or better.
98 Consequently you can only use it, if you are sure that your
99 software will run with Perl 5.8 or a later version.
100 Another disadvantage of using printf() is its cryptic syntax (maybe
102 not for you but translators of your software may have their own
103 opinion).
104 See the description of the function "__x()" in
106 Locale::TextDomain(3) for a much better way to get around this
107 problem.
108 Non-ASCII message ids ...
110 You should note that the function (and all other similar functions
112 in this module) does a bytewise comparison of the MSGID for the
113 lookup in the translation catalog, no matter whether obscure utf-8
114 flags are set on it, whether the string looks like utf-8, whether
115 the utf8(3pm) pragma is used, or whatever other weird method past
116 or future perl(1) versions invent for guessing character sets of
117 strings.
118 Using other than us-ascii characters in Perl source code is a call
120 for trouble, a compatibility nightmare. Furthermore, GNU gettext
121 only lately introduced support for non-ascii character sets in
122 sources, and support for this feature may not be available
123 everywhere. If you absolutely want to use MSGIDs in non-ascii
124 character sets, it is wise to choose utf-8. This will minimize the
125 risk that perl(1) itself will mess with the strings, and it will
126 also be a guaranty that you can later translate your project into
127 arbitrary target languages.
128 Other character sets can theoretically work. Yet, using another
130 character set in the Perl source code than the one used in your
131 message catalogs will never work, since the lookup is done
132 bytewise, and all strings with non-ascii characters will not be
133 found.
134 Even if you have solved all these problems, there is still one show
136 stopper left: The gettext runtime API lacks a possibility to
137 specify the character set of the source code (including the
138 original strings). Consequently - in absence of a hint for the
139 input encoding - strings without a translation are not subject to
140 output character set conversion. In other words: If the (non-
141 determinable) output character set differs from the character set
142 used in the source code, output can be a mixture of two character
143 sets. There is no point in trying to address this problem in the
144 pure Perl version of the gettext functions. because breaking
145 compatibilty between the Perl and the C version is a price too high
146 to pay.
147 This all boils down to: Only use ASCII characters in your
149 translatable strings!
150 dgettext TEXTDOMAIN, MSGID
152 Like gettext(), but retrieves the message for the specified
153 TEXTDOMAIN instead of the default domain. In case you wonder what
154 a textdomain is, you should really read on with
155 Locale::TextDomain(3).
156 dcgettext TEXTDOMAIN, MSGID, CATEGORY
158 Like dgettext() but retrieves the message from the specified
159 CATEGORY instead of the default category "LC_MESSAGES".
160 ngettext MSGID, MSGID_PLURAL, COUNT
162 Retrieves the correct translation for COUNT items. In legacy
163 software you will often find something like:
164 print "$count file(s) deleted.\n";
166 or
168 printf "$count file%s deleted.\n", $count == 1 ? '' : 's';
170 The first example looks awkward, the second will only work in
172 English and languages with similar plural rules. Before ngettext()
173 was introduced, the best practice for internationalized programs
174 was:
175 if ($count == 1) {
177 print gettext "One file deleted.\n";
178 } else {
179 printf gettext "%d files deleted.\n";
180 }
181 This is a nuisance for the programmer and often still not
183 sufficient for an adequate translation. Many languages have
184 completely different ideas on numerals. Some (French, Italian,
185 ...) treat 0 and 1 alike, others make no distinction at all
186 (Japanese, Korean, Chinese, ...), others have two or more plural
187 forms (Russian, Latvian, Czech, Polish, ...). The solution is:
188 printf (ngettext ("One file deleted.\n",
190 "%d files deleted.\n",
191 $count), # argument to ngettext!
192 $count); # argument to printf!
193 In English, or if no translation can be found, the first argument
195 (MSGID) is picked if $count is one, the second one otherwise. For
196 other languages, the correct plural form (of 1, 2, 3, 4, ...) is
197 automatically picked, too. You don't have to know anything about
198 the plural rules in the target language, ngettext() will take care
199 of that.
200 This is most of the time sufficient but you will have to prove your
202 creativity in cases like
203 printf "%d file(s) deleted, and %d file(s) created.\n";
205 dngettext TEXTDOMAIN, MSGID, MSGID_PLURAL, COUNT
207 Like ngettext() but retrieves the translation from the specified
208 textdomain instead of the default domain.
209 dcngettext TEXTDOMAIN, MSGID, MSGID_PLURAL, COUNT, CATEGORY
211 Like dngettext() but retrieves the translation from the specified
212 category, instead of the default category "LC_MESSAGES".
213 pgettext MSGCTXT, MSGID
215 Returns the translation of MSGID, given the context of MSGCTXT.
216 Both items are used as a unique key into the message catalog.
218 This allows the translator to have two entries for words that may
220 translate to different foreign words based on their context. For
221 example, the word "View" may be a noun or a verb, which may be used
222 in a menu as File->View or View->Source.
223 pgettext "Verb: To View", "View\n";
225 pgettext "Noun: A View", "View\n";
226 The above will both lookup different entries in the message
228 catalog.
229 A typical usage are GUI programs. Imagine a program with a main
231 menu and the notorious "Open" entry in the "File" menu. Now
232 imagine, there is another menu entry Preferences->Advanced->Policy
233 where you have a choice between the alternatives "Open" and
234 "Closed". In English, "Open" is the adequate text at both places.
235 In other languages, it is very likely that you need two different
236 translations. Therefore, you would now write:
237 pgettext "File|", "Open";
239 pgettext "Preferences|Advanced|Policy", "Open";
240 In English, or if no translation can be found, the second argument
242 (MSGID) is returned.
243 The function was introduced with libintl-perl version 1.17.
245 dpgettext TEXTDOMAIN, MSGCTXT, MSGID
247 Like pgettext(), but retrieves the message for the specified
248 TEXTDOMAIN instead of the default domain.
249 The function was introduced with libintl-perl version 1.17.
251 dcpgettext TEXTDOMAIN, MSGCTXT, MSGID, CATEGORY
253 Like dpgettext() but retrieves the message from the specified
254 CATEGORY instead of the default category "LC_MESSAGES".
255 The function was introduced with libintl-perl version 1.17.
257 npgettext MSGCTXT, MSGID, MSGID_PLURAL, COUNT
259 Like ngettext() with the addition of context as in pgettext().
260 In English, or if no translation can be found, the second argument
262 (MSGID) is picked if $count is one, the third one otherwise.
263 The function was introduced with libintl-perl version 1.17.
265 dnpgettext TEXTDOMAIN, MSGCTXT, MSGID, MSGID_PLURAL, COUNT
267 Like npgettext() but retrieves the translation from the specified
268 textdomain instead of the default domain.
269 The function was introduced with libintl-perl version 1.17.
271 dcnpgettext TEXTDOMAIN, MSGCTXT, MSGID, MSGID_PLURAL, COUNT, CATEGORY
273 Like dnpgettext() but retrieves the translation from the specified
274 category, instead of the default category "LC_MESSAGES".
275 The function was introduced with libintl-perl version 1.17.
277 textdomain TEXTDOMAIN
279 Sets the default textdomain (initially 'messages').
280 bindtextdomain TEXTDOMAIN, DIRECTORY
282 Binds TEXTDOMAIN to DIRECTORY. Huh? An example:
283 bindtextdomain "my-package", "./mylocale";
285 Say, the selected locale (actually the selected locale for category
287 "LC_MESSAGES") of the program is 'fr_CH', then the message catalog
288 will be expected in ./mylocale/fr_CH/LC_MESSAGES/my-package.mo.
289 bind_textdomain_codeset TEXTDOMAIN, ENCODING
291 Sets the output encoding for TEXTDOMAIN to ENCODING.
292 bind_textdomain_filter TEXTDOMAN, CODEREF, DATA
294 bind_textdomain_filter TEXTDOMAN, CODEREF
295 By default, Locale::Messages will turn the utf-8 flag of all
296 returned messages off. If you want to change this behavior, you
297 can pass a reference to a subroutine that does different things -
298 for example turn the utf-8 flag on, or leave it untouched. The
299 callback function will be called with DATA as the first, and the
300 possibly translated string as the second argument. It should
301 return the possibly modified string.
302 If you want an object method to be called, pass the object itself
304 in the data parameter and write a wrapper function. Example:
305 sub wrapper {
307 my ($string, $obj) = @_;
308 $obj->filterMethod ($string);
310 }
311 my $obj = MyPackage->new;
312 bind_textdomain_filter ('mydomain', \&wrapper, $obj);
314 The function cannot fail and always returns a true value.
316 Attention: If you use the function for setting the utf-8 flag, it
318 is your responsability to ensure that the output is really utf-8.
319 You should only use it, if you have set the environment variable
320 OUTPUT_CHARSET to "utf-8". Additionally you should call
321 bind_textdomain_codeset() with "utf-8" as the second argument.
322 Steven Haryanto has written a module Locale::TextDomain::UTF8(3pm)
324 that addresses the same problem.
325 This function has been introduced in libintl-perl 1.16 and it is
327 not part of the standard gettext API.
328 turn_utf_8_on VARIABLE
330 Returns VARIABLE but with the UTF-8 flag (only known in Perl >=5.6)
331 guaranteed to be turned on. This function does not really fit into
332 the module, but it is often handy nevertheless.
333 The flag does not mean that the string is in fact valid utf-8!
335 The function was introduced with libintl-perl version 1.16.
337 turn_utf_8_off VARIABLE
339 Returns VARIABLE but with the UTF-8 flag (only known in Perl >=5.6)
340 guaranteed to be turned off. This function does not really fit
341 into the module, but it is often handy nevertheless.
342 The function was introduced with libintl-perl version 1.07.
344 select_package PACKAGE
346 By default, Locale::Messages will try to load the XS version of the
347 gettext implementation, i. e. Locale::gettext_xs(3) and will fall
348 back to the pure Perl implementation Locale::gettext_pp(3). You
349 can override this behavior by passing the string "gettext_pp" or
350 "gettext_xs" to the function select_package(). Passing
351 "gettext_pp" here, will prefer the pure Perl implementation.
352 You will normally want to use that in a BEGIN block of your main
354 script.
355 The function was introduced with libintl-perl version 1.03 and is
357 not part of the standard gettext API.
358 Beginning with version 1.22 you can pass other package names than
360 "gettext_pp" or "gettext_xs" and use a completely different
361 backend. It is the caller's responsability to make sure that the
362 selected package offers the same interface as the two standard
363 packages.
364 One package that offers that functionality is
366 Locale::gettext_dumb(3pm).
367 nl_putenv ENVSPEC
369 Resembles the ANSI C putenv(3) function. The sole purpose of this
370 function is to work around some ideosyncrasies in the environment
371 processing of Windows systems. If you want to portably set or
372 unset environment variables, use this function instead of directly
373 manipulating %ENV.
374 The argument ENVSPEC may have three different forms.
376 LANGUAGE=fr_CH
378 This would set the environment variable "LANGUAGE" to
379 "fr_CH".
380 LANGUAGE=
382 Normally, this will set the environment variable "LANGUAGE"
383 to an empty string. Under Windows, however, the
384 environment variable will be deleted instead (and is no
385 longer present in %ENV). Since within libintl-perl empty
386 environment variables are useless, consider this usage as
387 deprecated.
388 LANGUAGE
390 This will delete the environment variable LANGUAGE. If you
391 are familiar with the brain-damaged implementation of
392 putenv(3) (resp. _putenv()) in the so-called standard C
393 library of MS-Windows, you may suspect that this is an
394 invalid argument. This is not the case! Passing a
395 variable name not followed by an equal sign will always
396 delete the variable, no matter which operating system you
397 use.
398 The function returns true for success, and false for failure.
400 Possible reasons for failure are an invalid syntax or - only under
401 Windows - failure to allocate space for the new environment entry
402 ($! will be set accordingly in this case).
403 Why all this hassle? The 32-bit versions of MS-DOS (currently
405 Windows 95/98/ME/NT/2000/XP/CE/.NET) maintain two distinct blocks
406 of environment variables per process. Which block is considered
407 the "correct" environment is a compile-time option of the Perl
408 interpreter. Unfortunately, if you have build the XS version
409 Locale::gettext_xs(3) under Windows, the underlying library may use
410 a different environment block, and changes you make to %ENV may not
411 be visible to the library.
412 The function nl_putenv() is mostly a funny way of saying
414 LANGUAGE=some_value
416 but it does its best, to pass this information to the gettext
418 library. Under other operating systems than Windows, it only
419 operates on %ENV, under Windows it will call the C library function
420 _putenv() (after doing some cleanup to its arguments), before
421 manipulating %ENV.
422 Please note, that your %ENV is updated by nl_putenv()
424 automatically.
425 The function has been introduced in libintl-perl version 1.10.
427 setlocale
429 Modifies and queries program's locale, see the documentation for
430 setlocale() in POSIX(3pm) instead.
431 On some systems, when using GNU gettext, a call from C to
433 setlocale() is - with the help of the C preprocessor - really a
434 call to libintl_setlocale(), which is in turn a wrapper around the
435 system setlocale(3). Failure to call libintl_setlocale() may lead
436 to certain malfunctions. On such systems,
437 Locale::Messages::setlocale() will call the wrapper
438 libintl_setlocale(). If you want to avoid problems, you should
439 therefore always call the setlocale() implementation in
440 Locale::Messages(3pm).
441 See <https://rt.cpan.org/Public/Bug/Display.html?id=83980> or
443 <https://savannah.gnu.org/bugs/?38162>, and
444 <https://savannah.gnu.org/bugs/?func=detailitem&item_id=44645> for
445 a discussion of the problem.
446 The function has been introduced in libintl-perl version 1.24.
448
450 You can (maybe) get the same constants from POSIX(3); see there for a
451 detailed description
452 LC_CTYPE
454 LC_NUMERIC
455 LC_TIME
456 LC_COLLATE
457 LC_MONETARY
458 LC_MESSAGES
459 This locale category was the reason that these constants from
460 POSIX(3) were included here. Even if it was present in your
461 systems C include file locale.h, it was not provided by POSIX(3).
462 Perl 5.8 and later seems to export the constant if available,
463 although it is not documented in POSIX(3).
464 Locale::Messages(3) makes an attempt to guess the value of this
466 category for all systems, and assumes the arbitrary value 1729
467 otherwise.
468 LC_ALL
470 If you specify the category LC_ALL as the first argument to
471 POSIX::setlocale(), all locale categories will be affected at once.
472
474 The module does not export anything unless explicitely requested. You
475 can import groups of functions via two tags:
476 use Locale::Messages (':locale_h')
478 Imports the functions that are normally defined in the C include
479 file locale.h:
480 gettext()
482 dgettext()
483 dcgettext()
484 ngettext()
485 dngettext()
486 dcngettext()
487 pgettext()
488 dpgettext()
489 dcpgettext()
490 npgettext()
491 dnpgettext()
492 dcnpgettext()
493 textdomain()
494 bindtextdomain()
495 bind_textdomain_codeset()
496 use Locale::Messages (':libintl_h')
497 Imports the locale category constants:
498 LC_CTYPE
500 LC_NUMERIC
501 LC_TIME
502 LC_COLLATE
503 LC_MONETARY
504 LC_MESSAGES
505 LC_ALL
506
508 select_package PACKAGE
509
511 A complete example:
512 1: use Locale::Messages qw(:locale_h :libintl_h);
514 2: use POSIX qw (setlocale);
515 3: setlocale (LC_MESSAGES, '');
516 4: textdomain ('my-package');
517 5: bindtextdomain ('my-package' => '/usr/local/share/locale');
518 6:
519 7: print gettext ("Hello world!\n");
520 Step by step: Line 1 imports the necessary functions and constants. In
522 line 3 we set the locale for category LC_MESSAGES to the default user
523 settings. For C programs you will often read that LC_ALL is the best
524 category here but this will also change the locale for LC_NUMERIC and
525 many programs will not work reliably after changing that category in
526 Perl; choose your own poison!
527 In line 4 we say that all messages (translations) without an explicit
529 domain specification should be retrieved from the message catalog for
530 the domain 'my-package'. Line 5 has the effect that the message
531 catalog will be searched under the directory /usr/local/share/locale.
532 If the user has selected the locale 'fr_CH', and if the file
534 /usr/local/share/locale/fr_CH/LC_MESSAGES/my-package.mo exists, and if
535 it contains a GNU message object file with a translation for the string
536 "Hello world!\n", then line 7 will print the French translation (for
537 Switzerland CH) to STDOUT.
538 The documentation for GNU gettext explains how to extract translatable
540 strings from your Perl files and how to create message catalogs.
541 Another less portable example: If your system uses the GNU libc you
543 should be able to find various files with the name libc.mo, the message
544 catalog for the library itself. If you have found these files under
545 /usr/share/locale, then you can try the following:
546 use Locale::Messages qw(:locale_h :libintl_h);
548 use POSIX qw (setlocale);
549 setlocale LC_MESSAGES, "";
551 textdomain "libc";
552 # The following is actually not needed, since this is
554 # one of the default search directories.
555 bindtextdomain libc => '/usr/share/locale';
556 bind_textdomain_codeset libc => 'iso-8859-1';
557 print gettext ("No such file or directory");
559 See Locale::TextDomain(3) for much simpler ways.
561
563 Copyright (C) 2002-2017 Guido Flohr <http://www.guido-flohr.net/>
564 (<mailto:guido.flohr@cantanea.com>), all rights reserved. See the
565 source code for details!code for details!
566
568 Locale::TextDomain(3pm), Locale::gettext_pp(3pm), Encode(3pm),
569 perllocale(3pm), POSIX(3pm), perl(1), gettext(1), gettext(3)
570
572 Hey! The above document had some coding errors, which are explained
573 below:
574 Around line 1001:
576 '=item' outside of any '=over'
577 Around line 1003:
579 You forgot a '=back' before '=head1'
580perl v5.34.0 2021-07-23 Locale::Messages(3)