1Locale::Messages(3)   User Contributed Perl Documentation  Locale::Messages(3)
2
3
4

NAME

6       Locale::Messages - Gettext Like Message Retrieval
7

SYNOPSIS

9        use Locale::Messages (:locale_h :libintl_h);
10
11        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

DESCRIPTION

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
45       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
52       The lower level module Locale::gettext_pp(3) provides the Perl
53       implementation of gettext() and related functions.
54

FUNCTIONS

56       The module exports by default nothing.  Every function has to be
57       imported explicitely or via an export tag ("EXPORT TAGS").
58
59       gettext MSGID
60           Returns the translation for MSGID.  Example:
61
62               print gettext "Hello World!\n";
63
64           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
68           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
72           One common mistake is this:
73
74               print gettext "Hello $name!";
75
76           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
81           Using printf() and friends has its own problems:
82
83               print sprintf (gettext ("This is the %s %s."), $color, $thing);
84
85           (The example is stupid because neither color nor thing will get
86           translated here ...).
87
88           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
95               "C'est le %$2s %$1s."
96
97           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
101           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
105           See the description of the function "__x()" in
106           Locale::TextDomain(3) for a much better way to get around this
107           problem.
108
109           Non-ASCII message ids ...
110
111           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
119           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
129           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
135           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
148           This all boils down to: Only use ASCII characters in your
149           translatable strings!
150
151       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
157       dcgettext TEXTDOMAIN, MSGID, CATEGORY
158           Like dgettext() but retrieves the message from the specified
159           CATEGORY instead of the default category "LC_MESSAGES".
160
161       ngettext MSGID, MSGID_PLURAL, COUNT
162           Retrieves the correct translation for COUNT items.  In legacy
163           software you will often find something like:
164
165               print "$count file(s) deleted.\n";
166
167           or
168
169               printf "$count file%s deleted.\n", $count == 1 ? '' : 's';
170
171           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
176               if ($count == 1) {
177                   print gettext "One file deleted.\n";
178               } else {
179                   printf gettext "%d files deleted.\n";
180               }
181
182           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
189               printf (ngettext ("One file deleted.\n",
190                                "%d files deleted.\n",
191                                $count), # argument to ngettext!
192                       $count);          # argument to printf!
193
194           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
201           This is most of the time sufficient but you will have to prove your
202           creativity in cases like
203
204               printf "%d file(s) deleted, and %d file(s) created.\n";
205
206       dngettext TEXTDOMAIN, MSGID, MSGID_PLURAL, COUNT
207           Like ngettext() but retrieves the translation from the specified
208           textdomain instead of the default domain.
209
210       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
214       pgettext MSGCTXT, MSGID
215           Returns the translation of MSGID, given the context of MSGCTXT.
216
217           Both items are used as a unique key into the message catalog.
218
219           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
224               pgettext "Verb: To View", "View\n";
225               pgettext "Noun: A View", "View\n";
226
227           The above will both lookup different entries in the message
228           catalog.
229
230           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
238               pgettext "File|", "Open";
239               pgettext "Preferences|Advanced|Policy", "Open";
240
241           In English, or if no translation can be found, the second argument
242           (MSGID) is returned.
243
244           The function was introduced with libintl-perl version 1.17.
245
246       dpgettext TEXTDOMAIN, MSGCTXT, MSGID
247           Like pgettext(), but retrieves the message for the specified
248           TEXTDOMAIN instead of the default domain.
249
250           The function was introduced with libintl-perl version 1.17.
251
252       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
256           The function was introduced with libintl-perl version 1.17.
257
258       npgettext MSGCTXT, MSGID, MSGID_PLURAL, COUNT
259           Like ngettext() with the addition of context as in pgettext().
260
261           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
264           The function was introduced with libintl-perl version 1.17.
265
266       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
270           The function was introduced with libintl-perl version 1.17.
271
272       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
276           The function was introduced with libintl-perl version 1.17.
277
278       textdomain TEXTDOMAIN
279           Sets the default textdomain (initially 'messages').
280
281       bindtextdomain TEXTDOMAIN, DIRECTORY
282           Binds TEXTDOMAIN to DIRECTORY.  Huh? An example:
283
284               bindtextdomain "my-package", "./mylocale";
285
286           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
290       bind_textdomain_codeset TEXTDOMAIN, ENCODING
291           Sets the output encoding for TEXTDOMAIN to ENCODING.
292
293       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
303           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
306               sub wrapper {
307                   my ($string, $obj) = @_;
308
309                   $obj->filterMethod ($string);
310               }
311               my $obj = MyPackage->new;
312
313               bind_textdomain_filter ('mydomain', \&wrapper, $obj);
314
315           The function cannot fail and always returns a true value.
316
317           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
323           This function has been introduced in libintl-perl 1.16 and it is
324           not part of the standard gettext API.
325
326       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
331           The flag does not mean that the string is in fact valid utf-8!
332
333           The function was introduced with libintl-perl version 1.16.
334
335       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
340           The function was introduced with libintl-perl version 1.07.
341
342       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
350           You will normally want to use that in a BEGIN block of your main
351           script.
352
353           The function was introduced with libintl-perl version 1.03 and is
354           not part of the standard gettext API.
355
356       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
363           The argument ENVSPEC may have three different forms.
364
365           LANGUAGE=fr_CH
366                   This would set the environment variable "LANGUAGE" to
367                   "fr_CH".
368
369           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
377           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
387           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
392           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
401           The function nl_putenv() is mostly a funny way of saying
402
403               LANGUAGE=some_value
404
405           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
411           Please note, that you %ENV is updated by nl_putenv() automatically.
412
413           The function has been introduced in libintl-perl version 1.10.
414

CONSTANTS

416       You can (maybe) get the same constants from POSIX(3); see there for a
417       detailed description
418
419       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
431           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
435       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

EXPORT TAGS

440       The module does not export anything unless explicitely requested.  You
441       can import groups of functions via two tags:
442
443       use Locale::Messages (':locale_h')
444           Imports the functions that are normally defined in the C include
445           file locale.h:
446
447           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
465           LC_CTYPE
466           LC_NUMERIC
467           LC_TIME
468           LC_COLLATE
469           LC_MONETARY
470           LC_MESSAGES
471           LC_ALL
472

OTHER EXPORTS

474       select_package PACKAGE
475

USAGE

477       A complete example:
478
479           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
487       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
494       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
499       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
505       The documentation for GNU gettext explains how to extract translatable
506       strings from your Perl files and how to create message catalogs.
507
508       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
513           use Locale::Messages qw (:locale_h :libintl_h);
514           use POSIX qw (setlocale);
515
516           setlocale LC_MESSAGES, "";
517           textdomain "libc";
518
519           # 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
524           print gettext ("No such file or directory");
525
526       See Locale::TextDomain(3) for much simpler ways.
527

AUTHOR

529       Copyright (C) 2002-2009, Guido Flohr <guido@imperia.net>, all rights
530       reserved.  See the source code for details.
531
532       This software is contributed to the Perl community by Imperia
533       (<http://www.imperia.net/>).
534

SEE ALSO

536       Locale::TextDomain(3pm), Locale::gettext_pp(3pm), Encode(3pm),
537       perllocale(3pm), POSIX(3pm), perl(1), gettext(1), gettext(3)
538

POD ERRORS

540       Hey! The above document had some coding errors, which are explained
541       below:
542
543       Around line 943:
544           '=item' outside of any '=over'
545
546       Around line 945:
547           You forgot a '=back' before '=head1'
548
549
550
551perl v5.12.0                      2010-05-02               Locale::Messages(3)
Impressum