1Locale::Messages(3) User Contributed Perl Documentation Locale::Messages(3)
2
6 Locale::Messages - Gettext Like Message Retrieval
7
9 use Locale::Messages (: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 %$2s %$1s."
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 This function has been introduced in libintl-perl 1.16 and it is
324 not part of the standard gettext API.
325 turn_utf_8_on VARIABLE
327 Returns VARIABLE but with the UTF-8 flag (only known in Perl >=5.6)
328 guaranteed to be turned on. This function does not really fit into
329 the module, but it is often handy nevertheless.
330 The flag does not mean that the string is in fact valid utf-8!
332 The function was introduced with libintl-perl version 1.16.
334 turn_utf_8_off VARIABLE
336 Returns VARIABLE but with the UTF-8 flag (only known in Perl >=5.6)
337 guaranteed to be turned off. This function does not really fit
338 into the module, but it is often handy nevertheless.
339 The function was introduced with libintl-perl version 1.07.
341 select_package PACKAGE
343 By default, Locale::Messages will try to load the XS version of the
344 gettext implementation, i. e. Locale::gettext_xs(3) and will fall
345 back to the pure Perl implementation Locale::gettext_pp(3). You
346 can override this behavior by passing the string "gettext_pp" or
347 "gettext_xs" to the function select_package(). Passing
348 "gettext_pp" here, will prefer the pure Perl implementation.
349 You will normally want to use that in a BEGIN block of your main
351 script.
352 The function was introduced with libintl-perl version 1.03 and is
354 not part of the standard gettext API.
355 nl_putenv ENVSPEC
357 Resembles the ANSI C putenv(3) function. The sole purpose of this
358 function is to work around some ideosyncrasies in the environment
359 processing of Windows systems. If you want to portably set or
360 unset environment variables, use this function instead of directly
361 manipulating %ENV.
362 The argument ENVSPEC may have three different forms.
364 LANGUAGE=fr_CH
366 This would set the environment variable "LANGUAGE" to
367 "fr_CH".
368 LANGUAGE=
370 Normally, this will set the environment variable "LANGUAGE"
371 to an empty string. Under Windows, however, the
372 environment variable will be deleted instead (and is no
373 longer present in %ENV). Since within libintl-perl empty
374 environment variables are useless, consider this usage as
375 deprecated.
376 LANGUAGE
378 This will delete the environment variable LANGUAGE. If you
379 are familiar with the brain-damaged implementation of
380 putenv(3) (resp. _putenv()) in the so-called standard C
381 library of MS-Windows, you may suspect that this is an
382 invalid argument. This is not the case! Passing a
383 variable name not followed by an equal sign will always
384 delete the variable, no matter which operating system you
385 use.
386 The function returns true for success, and false for failure.
388 Possible reasons for failure are an invalid syntax or - only under
389 Windows - failure to allocate space for the new environment entry
390 ($! will be set accordingly in this case).
391 Why all this hassle? The 32-bit versions of MS-DOS (currently
393 Windows 95/98/ME/NT/2000/XP/CE/.NET) maintain two distinct blocks
394 of environment variables per process. Which block is considered
395 the "correct" environment is a compile-time option of the Perl
396 interpreter. Unfortunately, if you have build the XS version
397 Locale::gettext_xs(3) under Windows, the underlying library may use
398 a different environment block, and changes you make to %ENV may not
399 be visible to the library.
400 The function nl_putenv() is mostly a funny way of saying
402 LANGUAGE=some_value
404 but it does its best, to pass this information to the gettext
406 library. Under other operating systems than Windows, it only
407 operates on %ENV, under Windows it will call the C library function
408 _putenv() (after doing some cleanup to its arguments), before
409 manipulating %ENV.
410 Please note, that you %ENV is updated by nl_putenv() automatically.
412 The function has been introduced in libintl-perl version 1.10.
414
416 You can (maybe) get the same constants from POSIX(3); see there for a
417 detailed description
418 LC_CTYPE
420 LC_NUMERIC
421 LC_TIME
422 LC_COLLATE
423 LC_MONETARY
424 LC_MESSAGES
425 This locale category was the reason that these constants from
426 POSIX(3) were included here. Even if it was present in your
427 systems C include file locale.h, it was not provided by POSIX(3).
428 Perl 5.8 and later seems to export the constant if available,
429 although it is not documented in POSIX(3).
430 Locale::Messages(3) makes an attempt to guess the value of this
432 category for all systems, and assumes the arbitrary value 1729
433 otherwise.
434 LC_ALL
436 If you specify the category LC_ALL as the first argument to
437 POSIX::setlocale(), all locale categories will be affected at once.
438
440 The module does not export anything unless explicitely requested. You
441 can import groups of functions via two tags:
442 use Locale::Messages (':locale_h')
444 Imports the functions that are normally defined in the C include
445 file locale.h:
446 gettext()
448 dgettext()
449 dcgettext()
450 ngettext()
451 dngettext()
452 dcngettext()
453 pgettext()
454 dpgettext()
455 dcpgettext()
456 npgettext()
457 dnpgettext()
458 dcnpgettext()
459 textdomain()
460 bindtextdomain()
461 bind_textdomain_codeset()
462 use Locale::Messages (':libintl_h')
463 Imports the locale category constants:
464 LC_CTYPE
466 LC_NUMERIC
467 LC_TIME
468 LC_COLLATE
469 LC_MONETARY
470 LC_MESSAGES
471 LC_ALL
472
474 select_package PACKAGE
475
477 A complete example:
478 1: use Locale::Messages qw (:locale_h :libintl_h);
480 2: use POSIX qw (setlocale);
481 3: setlocale (LC_MESSAGES, '');
482 4: textdomain ('my-package');
483 5: bindtextdomain ('my-package' => '/usr/local/share/locale');
484 6:
485 7: print gettext ("Hello world!\n");
486 Step by step: Line 1 imports the necessary functions and constants. In
488 line 3 we set the locale for category LC_MESSAGES to the default user
489 settings. For C programs you will often read that LC_ALL is the best
490 category here but this will also change the locale for LC_NUMERIC and
491 many programs will not work reliably after changing that category in
492 Perl; choose your own poison!
493 In line 4 we say that all messages (translations) without an explicit
495 domain specification should be retrieved from the message catalog for
496 the domain 'my-package'. Line 5 has the effect that the message
497 catalog will be searched under the directory /usr/local/share/locale.
498 If the user has selected the locale 'fr_CH', and if the file
500 /usr/local/share/locale/fr_CH/LC_MESSAGES/my-package.mo exists, and if
501 it contains a GNU message object file with a translation for the string
502 "Hello world!\n", then line 7 will print the French translation (for
503 Switzerland CH) to STDOUT.
504 The documentation for GNU gettext explains how to extract translatable
506 strings from your Perl files and how to create message catalogs.
507 Another less portable example: If your system uses the GNU libc you
509 should be able to find various files with the name libc.mo, the message
510 catalog for the library itself. If you have found these files under
511 /usr/share/locale, then you can try the following:
512 use Locale::Messages qw (:locale_h :libintl_h);
514 use POSIX qw (setlocale);
515 setlocale LC_MESSAGES, "";
517 textdomain "libc";
518 # The following is actually not needed, since this is
520 # one of the default search directories.
521 bindtextdomain libc => '/usr/share/locale';
522 bind_textdomain_codeset libc => 'iso-8859-1';
523 print gettext ("No such file or directory");
525 See Locale::TextDomain(3) for much simpler ways.
527
529 Copyright (C) 2002-2009, Guido Flohr <guido@imperia.net>, all rights
530 reserved. See the source code for details.
531 This software is contributed to the Perl community by Imperia
533 (<http://www.imperia.net/>).
534
536 Locale::TextDomain(3pm), Locale::gettext_pp(3pm), Encode(3pm),
537 perllocale(3pm), POSIX(3pm), perl(1), gettext(1), gettext(3)
538
540 Hey! The above document had some coding errors, which are explained
541 below:
542 Around line 943:
544 '=item' outside of any '=over'
545 Around line 945:
547 You forgot a '=back' before '=head1'
548perl v5.12.0 2010-05-02 Locale::Messages(3)