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: Many locales are only partially translated, so some 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        # NOT Ridas::Locales::Custom::en_GB_RIDAS !
229        my $l = DateTime::Locale->load('en_GB_RIDAS');
230
231       If you register a locale for an id that is already registered, the
232       "replace" parameter must be true or an exception will be thrown.
233
234       The complete name for a registered locale is generated by joining
235       together the language, territory, and variant components with a single
236       space.
237
238       This means that in the first example, the complete English and native
239       names for the locale would be "English United Kingdom Ridas Custom
240       Locale", and in the second example the complete English name is
241       "Hungarian Hungary", while the complete native name is "Magyar
242       Magyarorszag". The locale will be loadable by these complete names
243       (English and native), via the "load()" method.
244

ADDING CUSTOM LOCALES

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

SUPPORT

506       Please be aware that all locale data has been generated from the CLDR
507       (Common Locale Data Repository) project locales data). The data is
508       currently incomplete, and will contain errors in some locales.
509
510       When reporting errors in data, please check the primary data sources
511       first, then where necessary report errors directly to the primary
512       source via the CLDR bug report system. See
513       http://unicode.org/cldr/filing_bug_reports.html for details.
514
515       Once these errors have been confirmed, please forward the error report
516       and corrections to the DateTime mailing list, datetime@perl.org.
517
518       Support for this module is provided via the datetime@perl.org email
519       list. See http://lists.perl.org/ for more details.
520

DONATIONS

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

AUTHORS

541       Richard Evans <rich@ridas.com>
542
543       Dave Rolsky <autarch@urth.org>
544
545       These modules are loosely based on the DateTime::Language modules,
546       which were in turn based on the Date::Language modules from Graham
547       Barr's TimeDate distribution.
548

COPYRIGHT

550       Copyright (c) 2003 Richard Evans. Copyright (c) 2004-2008 David Rolsky.
551       All rights reserved. This program is free software; you can
552       redistribute it and/or modify it under the same terms as Perl itself.
553
554       This program is free software; you can redistribute it and/or modify it
555       under the same terms as Perl itself.
556
557       The full text of the license can be found in the LICENSE file included
558       with this module.
559
560       The locale modules in directory "DateTime/Locale/" have been generated
561       from data provided by the CLDR project, see
562       "DateTime/Locale/LICENSE.cldr" for details on the CLDR data's license.
563