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 qw(: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 %2$s %1$s."
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           Steven Haryanto has written a module Locale::TextDomain::UTF8(3pm)
324           that addresses the same problem.
325
326           This function has been introduced in libintl-perl 1.16 and it is
327           not part of the standard gettext API.
328
329       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
334           The flag does not mean that the string is in fact valid utf-8!
335
336           The function was introduced with libintl-perl version 1.16.
337
338       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
343           The function was introduced with libintl-perl version 1.07.
344
345       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
353           You will normally want to use that in a BEGIN block of your main
354           script.
355
356           The function was introduced with libintl-perl version 1.03 and is
357           not part of the standard gettext API.
358
359           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
365           One package that offers that functionality is
366           Locale::gettext_dumb(3pm).
367
368       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
375           The argument ENVSPEC may have three different forms.
376
377           LANGUAGE=fr_CH
378                   This would set the environment variable "LANGUAGE" to
379                   "fr_CH".
380
381           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
389           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
399           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
404           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
413           The function nl_putenv() is mostly a funny way of saying
414
415               LANGUAGE=some_value
416
417           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
423           Please note, that your %ENV is updated by nl_putenv()
424           automatically.
425
426           The function has been introduced in libintl-perl version 1.10.
427
428       setlocale
429           Modifies and queries program's locale, see the documentation for
430           setlocale() in POSIX(3pm) instead.
431
432           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
442           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
447           The function has been introduced in libintl-perl version 1.24.
448

CONSTANTS

450       You can (maybe) get the same constants from POSIX(3); see there for a
451       detailed description
452
453       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
465           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
469       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

EXPORT TAGS

474       The module does not export anything unless explicitely requested.  You
475       can import groups of functions via two tags:
476
477       use Locale::Messages (':locale_h')
478           Imports the functions that are normally defined in the C include
479           file locale.h:
480
481           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
499           LC_CTYPE
500           LC_NUMERIC
501           LC_TIME
502           LC_COLLATE
503           LC_MONETARY
504           LC_MESSAGES
505           LC_ALL
506

OTHER EXPORTS

508       select_package PACKAGE
509

USAGE

511       A complete example:
512
513           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
521       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
528       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
533       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
539       The documentation for GNU gettext explains how to extract translatable
540       strings from your Perl files and how to create message catalogs.
541
542       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
547           use Locale::Messages qw(:locale_h :libintl_h);
548           use POSIX qw (setlocale);
549
550           setlocale LC_MESSAGES, "";
551           textdomain "libc";
552
553           # 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
558           print gettext ("No such file or directory");
559
560       See Locale::TextDomain(3) for much simpler ways.
561

AUTHOR

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

SEE ALSO

568       Locale::TextDomain(3pm), Locale::gettext_pp(3pm), Encode(3pm),
569       perllocale(3pm), POSIX(3pm), perl(1), gettext(1), gettext(3)
570
571
572
573perl v5.38.0                      2023-07-21               Locale::Messages(3)
Impressum