DateTime::Locale(3pm)

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

NAME

6       DateTime::Locale - Localization support for DateTime.pm
7

SYNOPSIS

9         use DateTime::Locale;
10
11         my $loc = DateTime::Locale->load('en_GB');
12
13         print $loc->native_locale_name(),   "\n",
14               $loc->datetime_format_long(), "\n";
15
16         # but mostly just things like ...
17
18         my $dt = DateTime->now( locale => 'fr' );
19         print "Aujourd'hui le mois est " . $dt->month_name(), "\n";
20

DESCRIPTION

22       DateTime::Locale is primarily a factory for the various locale
23       subclasses. It also provides some functions for getting information on
24       all the available locales.
25
26       If you want to know what methods are available for locale objects, then
27       please read the "DateTime::Locale::Base" documentation.
28

USAGE

30       This module provides the following class methods:
31
32   DateTime::Locale->load( $locale_id | $locale_name | $alias )
33       Returns the locale object for the specified locale id, name, or alias -
34       see the "DateTime::Locale::Catalog" documentation for a list of built
35       in names and ids. The name provided may be either the English or native
36       name.
37
38       If the requested locale is not found, a fallback search takes place to
39       find a suitable replacement.
40
41       The fallback search order is:
42
43         {language}_{script}_{territory}
44         {language}_{script}
45         {language}_{territory}_{variant}
46         {language}_{territory}
47         {language}
48
49       Eg. For locale "es_XX_UNKNOWN" the fallback search would be:
50
51         es_XX_UNKNOWN   # Fails - no such locale
52         es_XX           # Fails - no such locale
53         es              # Found - the es locale is returned as the
54                         # closest match to the requested id
55
56       Eg. For locale "es_Latn_XX" the fallback search would be:
57
58         es_Latn_XX      # Fails - no such locale
59         es_Latn         # Fails - no such locale
60         es_XX           # Fails - no such locale
61         es              # Found - the es locale is returned as the
62                         # closest match to the requested id
63
64       If no suitable replacement is found, then an exception is thrown.
65
66       Please note that if you provide an id to this method, then the returned
67       locale object's "id()" method will always return the value you gave,
68       even if that value was an alias to some other id.
69
70       This is done for forwards compatibility, in case something that is
71       currently an alias becomes a unique locale in the future.
72
73       This means that the value of "$locale->id()" and the object's class may
74       not match.
75
76       The loaded locale is cached, so that locale objects may be singletons.
77       Calling "DateTime::Locale->register()",
78       "DateTime::Locale->add_aliases()", or
79       "DateTime::Locale->remove_alias()" clears the cache.
80
81   DateTime::Locale->ids()
82         my @ids = DateTime::Locale->ids();
83         my $ids = DateTime::Locale->ids();
84
85       Returns an unsorted list of the available locale ids, or an array
86       reference if called in a scalar context. This list does not include
87       aliases.
88
89   DateTime::Locale->names()
90         my @names = DateTime::Locale->names();
91         my $names = DateTime::Locale->names();
92
93       Returns an unsorted list of the available locale names in English, or
94       an array reference if called in a scalar context.
95
96   DateTime::Locale->native_names()
97         my @names = DateTime::Locale->native_names();
98         my $names = DateTime::Locale->native_names();
99
100       Returns an unsorted list of the available locale names in their native
101       language, or an array reference if called in a scalar context. All
102       native names are utf8 encoded.
103
104       NB: Some locales are only partially translated, so their native locale
105       names may still contain some English.
106
107   DateTime::Locale->add_aliases ( $alias1 => $id1, $alias2 => $id2, ... )
108       Adds an alias to an existing locale id. This allows a locale to be
109       loaded by its alias rather than id or name. Multiple aliases are
110       allowed.
111
112       If the passed locale id is neither registered nor listed in
113       DateTime::Local::Catalog's list of ids, an exception is thrown.
114
115        DateTime::Locale->add_aliases( LastResort => 'es_ES' );
116
117        # Equivalent to DateTime::Locale->load('es_ES');
118        DateTime::Locale->load('LastResort');
119
120       You can also pass a hash reference to this method.
121
122        DateTime::Locale->add_aliases( { Default     => 'en_GB',
123                                         Alternative => 'en_US',
124                                         LastResort  => 'es_ES' } );
125
126   DateTime::Locale->remove_alias( $alias )
127       Removes a locale id alias, and returns true if the specified alias
128       actually existed.
129
130        DateTime::Locale->add_aliases( LastResort => 'es_ES' );
131
132        # Equivalent to DateTime::Locale->load('es_ES');
133        DateTime::Locale->load('LastResort');
134
135        DateTime::Locale->remove_alias('LastResort');
136
137        # Throws an exception, 'LastResort' no longer exists
138        DateTime::Locale->load('LastResort');
139
140   DateTime::Locale->register( { ... }, { ... } )
141       This method allows you to register custom locales with the module. A
142       single locale is specified as a hash, and you may register multiple
143       locales at once by passing an array of hash references.
144
145       Until registered, custom locales cannot be instantiated via "load()"
146       and will not be returned by querying methods such as "ids()" or
147       "names()".
148
149        register( id           => $locale_id,
150                  en_language  => ..., # something like 'English' or 'Afar',
151
152                  # All other keys are optional. These are:
153                  en_script    => ...,
154                  en_territory => ...,
155                  en_variant   => ...,
156
157                  native_language  => ...,
158                  native_sript     => ...,
159                  native_territory => ...,
160                  native_variant   => ...,
161
162                  # Optional - defaults to DateTime::Locale::$locale_id
163                  class   => $class_name,
164
165                  replace => $boolean
166                )
167
168       The locale id and English name are required, and the following formats
169       should used wherever possible:
170
171        id:   languageId[_script][_territoryId[_variantId]]
172
173        Where:  languageId = Lower case ISO 639 code -
174                Always choose 639-1 over 639-2 where possible.
175
176        script = Title Case ISO 15924 script code
177
178        territoryId = Upper case ISO 3166 code -
179                      Always choose 3166-1 over 3166-2 where possible.
180
181        variantId = Upper case variant id -
182                    Basically anything you want, since this is typically the
183                    component that uniquely identifies a custom locale.
184
185       You cannot not use '@' or '=' in locale ids - these are reserved for
186       future use. The underscore (_) is the component separator, and should
187       not be used for any other purpose.
188
189       If the "native_*" components are supplied, they must be utf8 encoded.
190
191       If omitted, the native name is assumed to be identical to the English
192       name.
193
194       If class is supplied, it must be the full module name of your custom
195       locale. If omitted, the locale module is assumed to be a
196       DateTime::Locale subclass.
197
198       Examples:
199
200        DateTime::Locale->register
201            ( id           => 'en_GB_RIDAS',
202              en_language  => 'English',
203              en_territory => 'United Kingdom',
204              en_variant   => 'Ridas Custom Locale',
205            );
206
207        # Returns instance of class DateTime::Locale::en_GB_RIDAS
208        my $l = DateTime::Locale->load('en_GB_RIDAS');
209
210        DateTime::Locale->register
211            ( id               => 'hu_HU',
212              en_language      => 'Hungarian',
213              en_territory     => Hungary',
214              native_language  => 'Magyar',
215              native_territory => 'Magyarorszag',
216            );
217
218        # Returns instance of class DateTime::Locale::hu_HU
219        my $l = DateTime::Locale->load('hu_HU');
220
221        DateTime::Locale->register
222            ( id    => 'en_GB_RIDAS',
223              name  => 'English United Kingdom Ridas custom locale',
224              class => 'Ridas::Locales::CustomGB',
225            );
226
227        # Returns instance of class Ridas::Locales::CustomGB
228        my $l = DateTime::Locale->load('en_GB_RIDAS');
229
230       If you register a locale for an id that is already registered, the
231       "replace" parameter must be true or an exception will be thrown.
232
233       The complete name for a registered locale is generated by joining
234       together the language, territory, and variant components with a single
235       space.
236
237       This means that in the first example, the complete English and native
238       names for the locale would be "English United Kingdom Ridas Custom
239       Locale", and in the second example the complete English name is
240       "Hungarian Hungary", while the complete native name is "Magyar
241       Magyarorszag". The locale will be loadable by these complete names
242       (English and native), via the "load()" method.
243

ADDING CUSTOM LOCALES

245       These are added in one of two ways:
246
247       1.  Subclass an existing locale implementing only the changes you
248           require.
249
250       2.  Create a completely new locale as a new class.
251
252       In either case the locale MUST be registered before use.
253
254   Subclassing an existing locale
255       The following example sublasses the United Kingdom English locale to
256       change some the full date and time formats.
257
258         package Ridas::Locale::en_GB_RIDAS1;
259
260         use strict;
261         use DateTime::Locale::en_GB;
262
263         use base 'DateTime::Locale::en_GB';
264
265         sub date_format_full   { 'EEEE d MMMM y' }
266
267         sub time_format_full   { 'HH mm zzzz' }
268
269         1;
270
271       Now register it:
272
273        DateTime::Locale->register
274            ( id    => 'en_GB_RIDAS1',
275
276              # name, territory, and variant as described in register() documentation
277
278              class => 'Ridas::Locale::en_GB_RIDAS1',
279            );
280
281   Creating a completely new locale
282       You are, of course, free to subclass DateTime::Locale::Base if you want
283       to, though this is not required.
284
285       Remember to register your custom locale!
286
287       Of course, you can always do the registration in the module itself, and
288       simply load it before using it.
289
290       A completely new custom locale, one which does not subclass
291       DateTime::Locale::Base, must implement a number of methods.
292
293       The following methods can be used to get information about the locale's
294       id and name.
295
296       ·   $locale->id()
297
298           The complete locale id, something like "en_US".
299
300       ·   $locale->language_id()
301
302           The language portion of the id, like "en".
303
304       ·   $locale->script_id()
305
306           The script portion of the id, like "Hant".
307
308       ·   $locale->territory_id()
309
310           The territory portion of the id, like "US".
311
312       ·   $locale->variant_id()
313
314           The variant portion of the id, like "PREEURO".
315
316       ·   $locale->name()
317
318           The locale's complete name, which always includes at least a
319           language component, plus optional territory and variant components.
320           Something like "English United States". The value returned will
321           always be in English.
322
323       ·   $locale->language()
324
325       ·   $locale->script()
326
327       ·   $locale->territory()
328
329       ·   $locale->variant()
330
331           The relevant component from the locale's complete name, like
332           "English" or "United States".
333
334       ·   $locale->native_name()
335
336           The locale's complete name in localized form as a UTF-8 string.
337
338       ·   $locale->native_language()
339
340       ·   $locale->native_script()
341
342       ·   $locale->native_territory()
343
344       ·   $locale->native_variant()
345
346           The relevant component from the locale's complete native name as a
347           UTF-8 string.
348
349       The following methods all return an array reference containing the
350       specified data.
351
352       The methods with "format" in the name should return strings that can be
353       used a part of a string, like "the month of July". The stand alone
354       values are for use in things like calendars, and the narrow form may
355       not be unique (for example, in day column heading for a calendar it's
356       okay to have "T" for both Tuesday and Thursday).
357
358       The wide name should always be the full name of thing in question. The
359       narrow name should be just one or two characters.
360
361       ·   $locale->month_format_wide()
362
363       ·   $locale->month_format_abbreviated()
364
365       ·   $locale->month_format_narrow()
366
367       ·   $locale->month_stand_alone_wide()
368
369       ·   $locale->month_stand_alone_abbreviated()
370
371       ·   $locale->month_stand_alone_narrow()
372
373       ·   $locale->day_format_wide()
374
375       ·   $locale->day_format_abbreviated()
376
377       ·   $locale->day_format_narrow()
378
379       ·   $locale->day_stand_alone_wide()
380
381       ·   $locale->day_stand_alone_abbreviated()
382
383       ·   $locale->day_stand_alone_narrow()
384
385       ·   $locale->quarter_format_wide()
386
387       ·   $locale->quarter_format_abbreviated()
388
389       ·   $locale->quarter_format_narrow()
390
391       ·   $locale->quarter_stand_alone_wide()
392
393       ·   $locale->quarter_stand_alone_abbreviated()
394
395       ·   $locale->quarter_stand_alone_narrow()
396
397       ·   $locale->am_pm_abbreviated()
398
399       ·   $locale->era_wide()
400
401       ·   $locale->era_abbreviated()
402
403       ·   $locale->era_narrow()
404
405       The following methods return strings appropriate for the
406       "DateTime->format_cldr()" method:
407
408       ·   $locale->date_format_full()
409
410       ·   $locale->date_format_long()
411
412       ·   $locale->date_format_medium()
413
414       ·   $locale->date_format_short()
415
416       ·   $locale->date_format_default()
417
418       ·   $locale->time_format_full()
419
420       ·   $locale->time_format_long()
421
422       ·   $locale->time_format_medium()
423
424       ·   $locale->time_format_short()
425
426       ·   $locale->time_format_default()
427
428       ·   $locale->datetime_format_full()
429
430       ·   $locale->datetime_format_long()
431
432       ·   $locale->datetime_format_medium()
433
434       ·   $locale->datetime_format_short()
435
436       ·   $locale->datetime_format_default()
437
438       A locale may also offer one or more formats for displaying part of a
439       datetime, such as the year and month, or hour and minute.
440
441       ·   $locale->format_for($name)
442
443           These are accessed by passing a name to "$locale->format_for(...)",
444           where the name is a CLDR-style format specifier.
445
446           The return value is a string suitable for passing to
447           "$dt->format_cldr()", so you can do something like this:
448
449             print $dt->format_cldr( $dt->locale()->format_for('MMMdd') )
450
451           which for the "en" locale would print out something like "08 Jul".
452
453           Note that the localization may also include additional text
454           specific to the locale. For example, the "MMMMd" format for the
455           "zh" locale includes the Chinese characters for "day" (X) and month
456           (X), so you get something like "8X23X".
457
458       ·   $locale->available_formats()
459
460           This should return a list of all the format names that could be
461           passed to "$locale->format_for()".
462
463       The following methods deal with the default format lengths:
464
465       ·   $locale->default_date_format_length()
466
467       ·   $locale->default_time_format_length()
468
469           These methods return one of "full", "long", "medium", or "short",
470           indicating the current default format length.
471
472           The default when an object is created is determined by the CLDR
473           locale data.
474
475       ·   $locale->set_default_date_format_length($length)
476
477       ·   $locale->set_default_time_format_length($length)
478
479           These methods accept one of "full", "long", "medium", or "short",
480           indicating the new default format length.
481
482       There are also some miscellaneous methods locales should support:
483
484       ·   $locale->prefers_24_hour_time()
485
486           Returns a boolean indicating whether or not the locale prefers
487           24-hour time.
488
489       ·   $locale->first_day_of_week()
490
491           Returns a number from 1 to 7 indicating the local first day of the
492           week, with Monday being 1 and Sunday being 7.
493

SUPPORT

495       Please be aware that all locale data has been generated from the CLDR
496       (Common Locale Data Repository) project locales data). The data is
497       incomplete, and will contain errors in some locales.
498
499       When reporting errors in data, please check the primary data sources
500       first, then where necessary report errors directly to the primary
501       source via the CLDR bug report system. See
502       http://unicode.org/cldr/filing_bug_reports.html for details.
503
504       Once these errors have been confirmed, please forward the error report
505       and corrections to the DateTime mailing list, datetime@perl.org.
506
507       Support for this module is provided via the datetime@perl.org email
508       list. See http://lists.perl.org/ for more details.
509

DONATIONS

511       If you'd like to thank me for the work I've done on this module, please
512       consider making a "donation" to me via PayPal. I spend a lot of free
513       time creating free software, and would appreciate any support you'd
514       care to offer.
515
516       Please note that I am not suggesting that you must do this in order for
517       me to continue working on this particular software. I will continue to
518       do so, inasmuch as I have in the past, for as long as it interests me.
519
520       Similarly, a donation made in this way will probably not make me work
521       on this software much more, unless I get so many donations that I can
522       consider working on free software full time, which seems unlikely at
523       best.
524
525       To donate, log into PayPal and send money to autarch@urth.org or use
526       the button on this page:
527       <http://www.urth.org/~autarch/fs-donation.html>
528

AUTHORS

530       Richard Evans <rich@ridas.com>
531
532       Dave Rolsky <autarch@urth.org>
533
534       These modules are loosely based on the DateTime::Language modules,
535       which were in turn based on the Date::Language modules from Graham
536       Barr's TimeDate distribution.
537

COPYRIGHT

539       Copyright (c) 2003 Richard Evans. Copyright (c) 2004-2009 David Rolsky.
540       All rights reserved. This program is free software; you can
541       redistribute it and/or modify it under the same terms as Perl itself.
542
543       This program is free software; you can redistribute it and/or modify it
544       under the same terms as Perl itself.
545
546       The full text of the license can be found in the LICENSE file included
547       with this module.
548
549       The locale modules in directory DateTime/Locale/ have been generated
550       from data provided by the CLDR project, see
551       DateTime/Locale/LICENSE.cldr for details on the CLDR data's license.
552