3 perllocale - Perl locale handling (internationlization)
7 Perl supports language-specific notions of data such as "is this a
8 letter", "what is the upper-case equivalent of this letter", and
9 "which of these letters comes first". These are important issues,
10 especially for languages other than English - but also for English: it
11 would be very naÔve to think that C<A-Za-z> defines all the "letters".
12 Perl is also aware that some character other than '.' may be preferred
13 as a decimal point, and that output date representations may be
16 Perl can understand language-specific data via the standardized
17 (ISO C, XPG4, POSIX 1.c) method called "the locale system".
18 The locale system is controlled per application using a pragma, one
19 function call, and several environment variables.
21 B<NOTE>: This feature is new in Perl 5.004, and does not apply unless
22 an application specifically requests it - see L<Backward
25 =head1 PREPARING TO USE LOCALES
27 If Perl applications are to be able to understand and present your
28 data correctly according a locale of your choice, B<all> of the following
35 B<Your operating system must support the locale system>. If it does,
36 you should find that the C<setlocale> function is a documented part of
41 B<Definitions for the locales which you use must be installed>. You,
42 or your system administrator, must make sure that this is the case.
43 The available locales, the location in which they are kept, and the
44 manner in which they are installed, vary from system to system. Some
45 systems provide only a few, hard-wired, locales, and do not allow more
46 to be added; others allow you to add "canned" locales provided by the
47 system supplier; still others allow you or the system administrator
48 to define and add arbitrary locales. (You may have to ask your
49 supplier to provide canned locales whch are not delivered with your
50 operating system.) Read your system documentation for further
55 B<Perl must believe that the locale system is supported>. If it does,
56 C<perl -V:d_setlocale> will say that the value for C<d_setlocale> is
61 If you want a Perl application to process and present your data
62 according to a particular locale, the application code should include
63 the S<C<use locale>> pragma (L<The use locale Pragma>) where
64 appropriate, and B<at least one> of the following must be true:
70 B<The locale-determining environment variables (see L<ENVIRONMENT>) must
71 be correctly set up>, either by yourself, or by the person who set up
72 your system account, at the time the application is started.
76 B<The application must set its own locale> using the method described
77 in L<The C<setlocale> function>.
83 =head2 The use locale pragma
85 By default, Perl ignores the current locale. The S<C<use locale>> pragma
86 tells Perl to use the current locale for some operations:
92 B<The comparison operators> (C<lt>, C<le>, C<cmp>, C<ge>, and C<gt>)
93 use C<LC_COLLATE>. The C<sort> function is also affected if it is
94 used without an explicit comparison function because it uses C<cmp> by
97 B<Note:> The C<eq> and C<ne> operators are unaffected by the locale:
98 they always perform a byte-by-byte comparison of their scalar
99 arguments. If you really want to know if two strings - which C<eq>
100 may consider different - are equal as far as collation is concerned,
103 !("space and case ignored" cmp "SpaceAndCaseIgnored")
105 (which would be true if the collation locale specified a
106 dictionary-like ordering).
108 I<Editor's note:> I am right about C<eq> and C<ne>, aren't I?
112 B<Regular expressions and case-modification functions> (C<uc>,
113 C<lc>, C<ucfirst>, and C<lcfirst>) use C<LC_CTYPE>
117 B<The formatting functions> (C<printf> and C<sprintf>) use
122 B<The POSIX date formatting function> (C<strftime>) uses C<LC_TIME>.
126 C<LC_COLLATE>, C<LC_CTYPE>, and so on, are discussed further in
127 L<LOCALE CATEGORIES>.
129 The default behaviour returns with S<C<no locale>> or on reaching the end
130 of the enclosing block.
132 Note that the result of any operation that uses locale information is
133 tainted (see L<perlsec.pod>), since locales can be created by
134 unprivileged users on some systems.
136 =head2 The setlocale function
138 You can switch locales as often as you wish at runtime with the
139 C<POSIX::setlocale> function:
141 # This functionality not usable prior to Perl 5.004
144 # Import locale-handling tool set from POSIX module.
145 # This example uses: setlocale -- the function call
146 # LC_CTYPE -- explained below
147 use POSIX qw(locale_h);
149 # query and save the old locale.
150 $old_locale = setlocale(LC_CTYPE);
152 setlocale(LC_CTYPE, "fr_CA.ISO8859-1");
153 # LC_CTYPE now in locale "French, Canada, codeset ISO 8859-1"
155 setlocale(LC_CTYPE, "");
156 # LC_CTYPE now reset to default defined by LC_ALL/LC_CTYPE/LANG
157 # environment variables. See below for documentation.
159 # restore the old locale
160 setlocale(LC_CTYPE, $old_locale);
162 The first argument of C<setlocale> gives the B<category>, the second
163 the B<locale>. The category tells in what aspect of data processing
164 you want to apply locale-specific rules. Category names are discussed
165 in L<LOCALE CATEGORIES> and L<ENVIRONMENT>. The locale is the name of
166 a collection of customization information corresponding to a paricular
167 combination of language, country or territory, and codeset. Read on
168 for hints on the naming of locales: not all systems name locales as in
171 If no second argument is provided, the function returns a string
172 naming the current locale for the category. You can use this value as
173 the second argument in a subsequent call to C<setlocale>. If a second
174 argument is given and it corresponds to a valid locale, the locale for
175 the category is set to that value, and the function returns the
176 now-current locale value. You can use this in a subsequent call to
177 C<setlocale>. (In some implementations, the return value may sometimes
178 differ from the value you gave as the second argument - think of it as
179 an alias for the value that you gave.)
181 As the example shows, if the second argument is an empty string, the
182 category's locale is returned to the default specified by the
183 corresponding environment variables. Generally, this results in a
184 return to the default which was in force when Perl started up: changes
185 to the environment made by the application after start-up may or may
186 not be noticed, depending on the implementation of your system's C
189 If the second argument does not correspond to a valid locale, the
190 locale for the category is not changed, and the function returns
193 For further information about the categories, consult
194 L<setlocale(3)>. For the locales available in your system,
195 also consult L<setlocale(3)> and see whether it leads you
196 to the list of the available locales (search for the C<SEE ALSO>
197 section). If that fails, try the following command lines:
209 and see whether they list something resembling these
211 en_US.ISO8859-1 de_DE.ISO8859-1 ru_RU.ISO8859-5
214 english german russian
215 english.iso88591 german.iso88591 russian.iso88595
217 Sadly, even though the calling interface for C<setlocale> has been
218 standardized, the names of the locales have not. The form of the name
219 is usually I<language_country>B</>I<territory>B<.>I<codeset>, but the
220 latter parts are not always present.
222 Two special locales are worth particular mention: "C" and
223 "POSIX". Currently these are effectively the same locale: the
224 difference is mainly that the first one is defined by the C standard
225 and the second by the POSIX standard. What they define is the
226 B<default locale> in which every program starts in the absence of
227 locale information in its environment. (The default default locale,
228 if you will.) Its language is (American) English and its character
231 B<NOTE>: Not all systems have the "POSIX" locale (not all systems
232 are POSIX-conformant), so use "C" when you need explicitly to
233 specify this default locale.
235 =head2 The localeconv function
237 The C<POSIX::localeconv> function allows you to get particulars of the
238 locale-dependent numeric formatting information specified by the
239 current C<LC_NUMERIC> and C<LC_MONETARY> locales. (If you just want
240 the name of the current locale for a particular category, use
241 C<POSIX::setlocale> with a single parameter - see L<The setlocale
244 use POSIX qw(locale_h);
247 # Get a reference to a hash of locale-dependent info
248 $locale_values = localeconv();
250 # Output sorted list of the values
251 for (sort keys %$locale_values) {
252 printf "%-20s = %s\n", $_, $locale_values->{$_}
255 C<localeconv> takes no arguments, and returns B<a reference to> a
256 hash. The keys of this hash are formatting variable names such as
257 C<decimal_point> and C<thousands_sep>; the values are the
258 corresponding values. See L<POSIX (3)/localeconv> for a longer
259 example, which lists all the categories an implementation might be
260 expected to provide; some provide more and others fewer, however.
262 I<Editor's note:> I can't work out whether C<POSIX::localeconv>
263 correctly obeys C<use locale> and C<no locale>. In my opinion, it
264 should, if only to be consistent with other locale stuff - although
265 it's hardly a show-stopper if it doesn't. Could someone check,
268 Here's a simple-minded example program which rewrites its command line
269 parameters as integers formatted correctly in the current locale:
271 # See comments in previous example
273 use POSIX qw(locale_h);
276 # Get some of locale's numeric formatting parameters
277 my ($thousands_sep, $grouping) =
278 @{localeconv()}{'thousands_sep', 'grouping'};
280 # Apply defaults if values are missing
281 $thousands_sep = ',' unless $thousands_sep;
282 $grouping = 3 unless $grouping;
284 # Format command line params for current locale
287 $_ = int; # Chop non-integer part
289 s/(\d)(\d{$grouping}($|$thousands_sep))/$1$thousands_sep$2/;
294 I<Editor's note:> Like all the examples, this needs testing on systems
295 which, unlike mine, have non-toy implementations of locale handling.
297 =head1 LOCALE CATEGORIES
299 The subsections which follow descibe basic locale categories. As well
300 as these, there are some combination categories which allow the
301 manipulation of of more than one basic category at a time. See
302 L<ENVIRONMENT VARIABLES> for a discussion of these.
304 =head2 Category LC_COLLATE: Collation
306 When in the scope of S<C<use locale>>, Perl looks to the B<LC_COLLATE>
307 environment variable to determine the application's notions on the
308 collation (ordering) of characters. ('B' follows 'A' in Latin
309 alphabets, but where do '¡' and '' belong?)
311 Here is a code snippet that will tell you what are the alphanumeric
312 characters in the current locale, in the locale order:
315 print +(sort grep /\w/, map { chr() } 0..255), "\n";
317 I<Editor's note:> The original example had C<setlocale(LC_COLLATE, "")>
318 prior to C<print ...>. I think this is wrong: as soon as you utter
319 S<C<use locale>>, the default behaviour of C<sort> (well, C<cmp>, really)
320 becomes locale-aware. The locale it's aware of is the current locale
321 which, unless you've changed it yourself, is the default locale
322 defined by your environment.
324 Compare this with the characters that you see and their order if you state
325 explicitly that the locale should be ignored:
328 print +(sort grep /\w/, map { chr() } 0..255), "\n";
330 This machine-native collation (which is what you get unless S<C<use
331 locale>> has appeared earlier in the same block) must be used for
332 sorting raw binary data, whereas the locale-dependent collation of the
333 first example is useful for written text.
335 B<NOTE>: In some locales some characters may have no collation value
336 at all - for example, if '-' is such a character, 'relocate' and
337 're-locate' may be considered to be equal to each other, and so sort
338 to the same position.
340 =head2 Category LC_CTYPE: Character Types
342 When in the scope of S<C<use locale>>, Perl obeys the C<LC_CTYPE> locale
343 setting. This controls the application's notion of which characters
344 are alphabetic. This affects Perl's C<\w> regular expression
345 metanotation, which stands for alphanumeric characters - that is,
346 alphabetic and numeric characters. (Consult L<perlre> for more
347 information about regular expressions.) Thanks to C<LC_CTYPE>,
348 depending on your locale setting, characters like '', '',
349 'þ', and '¯' may be understood as C<\w> characters.
351 C<LC_CTYPE> also affects the POSIX character-class test functions -
352 C<isalpha>, C<islower> and so on. For example, if you move from the
353 "C" locale to a 7-bit Scandinavian one, you may find - possibly to
354 your surprise -that "|" moves from the C<ispunct> class to C<isalpha>.
356 I<Editor's note:> I can't work out whether the C<POSIX::is...> stuff
357 correctly obeys C<use locale> and C<no locale>. In my opinion, they
358 should. Could someone check, please?
360 B<Note:> A broken or malicious C<LC_CTYPE> locale definition may
361 result in clearly ineligible characters being considered to be
362 alphanumeric by your application. For strict matching of (unaccented)
363 letters and digits - for example, in command strings - locale-aware
364 applications should use C<\w> inside a C<no locale> block.
366 =head2 Category LC_NUMERIC: Numeric Formatting
368 When in the scope of S<C<use locale>>, Perl obeys the C<LC_NUMERIC>
369 locale information which controls application's idea of how numbers
370 should be formatted for human readability by the C<printf>, C<fprintf>,
371 and C<write> functions. String to numeric conversion by the
372 C<POSIX::strtod> function is also affected. In most impementations
373 the only effect is to change the character used for the decimal point
374 - perhaps from '.' to ',': these functions aren't aware of such
375 niceties as thousands separation and so on. (See L<The localeconv
376 function> if you care about these things.)
378 I<Editor's note:> I can't work out whether C<POSIX::strtod> correctly
379 obeys C<use locale> and C<no locale>. In my opinion, it should -
380 although it's hardly a show-stopper if it doesn't. Could someone
383 Note that output produced by C<print> is B<never> affected by the
384 current locale: it is independent of whether C<use locale> or C<no
385 locale> is in effect, and corresponds to what you'd get from C<printf>
386 in the "C" locale. The same is true for Perl's internal conversions
387 between numeric and string formats:
389 use POSIX qw(strtod);
391 $n = 5/2; # Assign numeric 2.5 to $n
393 $a = " $n"; # Locale-independent conversion to string
395 print "half five is $n\n"; # Locale-independent output
397 printf "half five is %g\n", $n; # Locale-dependent output
399 print "DECIMAL POINT IS COMMA\n" # Locale-dependent conversion
400 if $n == (strtod("2,5"))[0];
402 =head2 Category LC_MONETARY: Formatting of monetary amounts
404 The C standard defines the C<LC_MONETARY> category, but no function
405 that is affected by its contents. (Those with experience of standards
406 committees will recognise that the working group decided to punt on
407 the issue.) Consequently, Perl takes no notice of it. If you really
408 want to use C<LC_MONETARY>, you can query its contents - see L<The
409 localeconv function> - and use the information that it returns in your
410 application's own formating of currency amounts. However, you may
411 well find that the information, though voluminous and complex, does
412 not quite meet your requirements: currency formatting is a hard nut to
417 The output produced by C<POSIX::strftime>, which builds a formatted
418 human-readable date/time string, is affected by the current C<LC_TIME>
419 locale. Thus, in a French locale, the output produced by the C<%B>
420 format element (full month name) for the first month of the year would
421 be "janvier". Here's how to get a list of the long month names in the
424 use POSIX qw(strftime);
428 $long_month_name[$_] = strftime("%B", 0, 0, 0, 1, $_, 96);
431 I<Editor's note:> Unchecked in "alien" locales: my system can't do
434 =head2 Other categories
436 The remaining locale category, C<LC_MESSAGES> (possibly supplemented by
437 others in particular implementations) is not currently used by Perl -
438 except possibly to affect the behaviour of library functions called
439 by extensions which are not part of the standard Perl distribution.
447 A string that controls whether Perl warns in its startup about failed
448 locale settings. This can happen if the locale support in the
449 operating system is lacking (broken) is some way. If this string has
450 an integer value differing from zero, Perl will not complain.
452 B<NOTE>: This is just hiding the warning message. The message tells
453 about some problem in your system's locale support and you should
454 investigate what the problem is.
458 The following environment variables are not specific to Perl: They are
459 part of the standardized (ISO C, XPG4, POSIX 1.c) setlocale method to
460 control an application's opinion on data.
466 C<LC_ALL> is the "override-all" locale environment variable. If it is
467 set, it overrides all the rest of the locale environment variables.
471 In the absence of C<LC_ALL>, C<LC_CTYPE> chooses the character type
472 locale. In the absence of both C<LC_ALL> and C<LC_CTYPE>, C<LANG>
473 chooses the character type locale.
477 In the absence of C<LC_ALL>, C<LC_COLLATE> chooses the collation (sorting)
478 locale. In the absence of both C<LC_ALL> and C<LC_COLLATE>, C<LANG>
479 chooses the collation locale.
483 In the absence of C<LC_ALL>, C<LC_MONETARY> chooses the montary formatting
484 locale. In the absence of both C<LC_ALL> and C<LC_MONETARY>, C<LANG>
485 chooses the monetary formatting locale.
489 In the absence of C<LC_ALL>, C<LC_NUMERIC> chooses the numeric format
490 locale. In the absence of both C<LC_ALL> and C<LC_NUMERIC>, C<LANG>
491 chooses the numeric format.
495 In the absence of C<LC_ALL>, C<LC_TIME> chooses the date and time formatting
496 locale. In the absence of both C<LC_ALL> and C<LC_TIME>, C<LANG>
497 chooses the date and time formatting locale.
501 C<LANG> is the "catch-all" locale environment variable. If it is set,
502 it is used as the last resort after the overall C<LC_ALL> and the
503 category-specific C<LC_...>.
509 =head2 Backward compatibility
511 Versions of Perl prior to 5.004 ignored locale information, generally
512 behaving as if something similar to the C<"C"> locale (see L<The
513 setlocale function>) was always in force, even if the program
514 environment suggested otherwise. By default, Perl still behaves this
515 way so as to maintain backward compatibility. If you want a Perl
516 application to pay attention to locale information, you B<must> use
517 the S<C<use locale>> pragma (see L<The S<C<use locale>> Pragma>) to
518 instruct it to do so.
522 Comparing and sorting by locale is usually slower than the default
523 sorting; factors of 2 to 4 have been observed. It will also consume
524 more memory: while a Perl scalar variable is participating in any
525 string comparison or sorting operation and obeying the locale
526 collation rules it will take about 3-15 (the exact value depends on
527 the operating system and the locale) times more memory than normally.
528 These downsides are dictated more by the operating system
529 implementation of the locale system than by Perl.
533 In Perl 5.003 (and later development releases prior to 5.003_06),
534 per-locale collation was possible using the C<I18N::Collate> library
535 module. This is now mildly obsolete and should be avoided in new
536 applications. The C<LC_COLLATE> functionality is integrated into the
537 Perl core language and one can use locale-specific scalar data
538 completely normally - there is no need to juggle with the scalar
539 references of C<I18N::Collate>.
541 =head2 An imperfect standard
543 Internationalization, as defined in the C and POSIX standards, can be
544 criticized as incomplete, ungainly, and having too large a
545 granularity. (Locales apply to a whole process, when it would
546 arguably be more useful to have them apply to a single thread, window
547 group, or whatever.) They also have a tendency, like standards
548 groups, to divide the world into nations, when we all know that the
549 world can equally well be divided into bankers, bikers, gamers, and so
550 on. But, for now, it's the only standard we've got. This may be
553 =head2 Freely available locale definitions
555 There is a large collection of locale definitions at
556 C<ftp://dkuug.dk/i18n/WG15-collection>. You should be aware that they
557 are unsupported, and are not claimed to be fit for any purpose. If
558 your system allows the installation of arbitrary locales, you may find
559 them useful as they are, or as a basis for the development of your own
564 Internationalization is often abbreviated as B<i18n> because its first
565 and last letters are separated by eighteen others. You can also talk of
566 localization (B<l10n>), the process of tailoring an
567 internationalizated application for use in a particular locale.
571 =head2 Broken systems
573 In certain system environments the operating system's locale support
574 is broken and cannot be fixed or used by Perl. Such deficiencies can
575 and will result in mysterious hangs and/or Perl core dumps. One
576 example is IRIX before release 6.2, in which the C<LC_COLLATE> support
577 simply does not work. When confronted with such a system, please
578 report in excruciating detail to C<perlbug@perl.com>, and complain to
579 your vendor: maybe some bug fixes exist for these problems in your
580 operating system. Sometimes such bug fixes are called an operating
583 =head2 Rendering of this documentation
585 This manual page contains non-ASCII characters, which should all be
586 rendered as accented letters, and which should make some sort of sense
587 in context. If this is not the case, your system is probably not
588 using the ISO 8859-1 character set which was used to write them,
589 and/or your formatting, display, and printing software are not
590 correctly mapping them to your host's character set. If this annoys
591 you, and if you can convince yourself that it is due to a bug in one
592 of Perl's various C<pod2>... utilities, by all means report it as a
593 Perl bug. Otherwise, pausing only to curse anyone who ever invented
594 yet another character set, see if you can make it handle ISO 8859-1
599 L<POSIX (3)/isalnum>, L<POSIX (3)/isalpha>, L<POSIX (3)/isdigit>,
600 L<POSIX (3)/isgraph>, L<POSIX (3)/islower>, L<POSIX (3)/isprint>,
601 L<POSIX (3)/ispunct>, L<POSIX (3)/isspace>, L<POSIX (3)/isupper>,
602 L<POSIX (3)/isxdigit>, L<POSIX (3)/localeconv>, L<POSIX (3)/setlocale>,
605 I<Editor's note:> That looks horrible after going through C<pod2man>.
606 But I do want to call out all thse sectins by name. What should I
611 Perl 5.003's F<perli18n.pod> heavily hacked by Dominic Dunlop.
614 Mon Dec 16 14:13:10 WET 1996