1DateTime::Locale(3) User Contributed Perl Documentation DateTime::Locale(3)
2
6 DateTime::Locale - Localization support for DateTime.pm
7
9 use DateTime::Locale;
10 my $loc = DateTime::Locale->load('en_GB');
12 print $loc->native_locale_name, "\n",
14 $loc->long_datetime_format, "\n";
15 # but mostly just things like ...
17 my $dt = DateTime->now( locale => 'fr' );
19 print "Aujourd'hui le mois est " . $dt->month_name, "\n":
20
22 DateTime::Locale is primarily a factory for the various locale sub‐
23 classes. It also provides some functions for getting information on
24 available locales.
25 If you want to know what methods are available for locale objects, then
27 please read the "DateTime::Locale::Base" documentation.
28
30 This module provides the following class methods:
31 * load( $locale_id ⎪ $locale_name ⎪ $alias )
33 Returns the locale object for the specified locale id, name, or
34 alias - see the "DateTime::LocaleCatalog" documentation for a list
35 of built in names and ids. The name provided may be either the
36 English or native name.
37 If the requested locale is not found, a fallback search takes place
39 to find a suitable replacement.
40 The fallback search order is:
42 language_script_territory
44 language_script
45 language_territory_variant
46 language_territory
47 language
48 Eg. For locale "es_XX_UNKNOWN" the fallback search would be:
50 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 Eg. For locale "es_Latn_XX" the fallback search would be:
57 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 If no suitable replacement is found, then an exception is thrown.
65 Please note that if you provide an id to this method, then the
67 returned locale object's "id()" method will always return the value
68 you gave, even if that value was an alias to some other id.
69 This is done for forwards compatibility, in case something that is
71 currently an alias becomes a unique locale in the future.
72 This means that the value of "id()" and the object's class may not
74 match.
75 The loaded locale is cached, so that locale objects may be single‐
77 tons. Calling "register()", "add_aliases()", or "remove_alias()"
78 clears the cache.
79 * ids
81 my @ids = DateTime::Locale->ids;
82 my $ids = DateTime::Locale->ids;
83 Returns an unsorted list of the available locale ids, or an array
85 reference if called in a scalar context. This list does not
86 include aliases.
87 * names
89 my @names = DateTime::Locale->names;
90 my $names = DateTime::Locale->names;
91 Returns an unsorted list of the available locale names in English,
93 or an array reference if called in a scalar context.
94 * native_names
96 my @names = DateTime::Locale->native_names;
97 my $names = DateTime::Locale->native_names;
98 Returns an unsorted list of the available locale names in their
100 native language, or an array reference if called in a scalar con‐
101 text. All native names are utf8 encoded.
102 NB: Many locales are only partially translated, so some native
104 locale names may still contain some English.
105 * add_aliases ( $alias1 => $id1, $alias2 => $id2, ... )
107 Adds an alias to an existing locale id. This allows a locale to be
108 "load()"ed by its alias rather than id or name. Multiple aliases
109 are allowed.
110 If the passed locale id is neither registered nor listed in "AVAIL‐
112 ABLE LOCALES", an exception is thrown.
113 DateTime::Locale->add_aliases( LastResort => 'es_ES' );
115 # Equivalent to DateTime::Locale->load('es_ES');
117 DateTime::Locale->load('LastResort');
118 You can also pass a hash reference to this method.
120 DateTime::Locale->add_aliases( { Default => 'en_GB',
122 Alternative => 'en_US',
123 LastResort => 'es_ES' } );
124 * remove_alias( $alias )
126 Removes a locale id alias, and returns true if the specified alias
127 actually existed.
128 DateTime::Locale->add_aliases( LastResort => 'es_ES' );
130 # Equivalent to DateTime::Locale->load('es_ES');
132 DateTime::Locale->load('LastResort');
133 DateTime::Locale->remove_alias('LastResort');
135 # Throws an exception, 'LastResort' no longer exists
137 DateTime::Locale->load('LastResort');
138 * register( { ... }, { ... } )
140 This method allows you to register custom locales with the module.
141 A single locale is specified as a hash, and you may register multi‐
142 ple locales at once by passing an array of hash references.
143 Until registered, custom locales cannot be instantiated via
145 "load()" and will not be returned by querying methods such as
146 "ids()" or "names()".
147 register( id => $locale_id,
149 en_language => ..., # something like 'English' or 'Afar',
150 # All other keys are optional. These are:
152 en_script => ...,
153 en_territory => ...,
154 en_variant => ...,
155 native_language => ...,
157 native_sript => ...,
158 native_territory => ...,
159 native_variant => ...,
160 # Optional - defaults to DateTime::Locale::$locale_id
162 class => $class_name,
163 replace => $boolean
165 )
166 The locale id and English name are required, and the following for‐
168 mats should used wherever possible:
169 id: languageId[_script][_territoryId[_variantId]]
171 Where: languageId = Lower case ISO 639 code -
173 Always choose 639-1 over 639-2 where possible.
174 script = Title Case ISO 15924 script code
176 territoryId = Upper case ISO 3166 code -
178 Always choose 3166-1 over 3166-2 where possible.
179 variantId = Upper case variant id -
181 Basically anything you want, since this is typically the
182 component that uniquely identifies a custom locale.
183 You cannot not use '@' or '=' in locale ids - these are reserved
185 for future use. The underscore (_) is the component separator, and
186 should not be used for any other purpose.
187 If the "native_*" components are supplied, they must be utf8
189 encoded and follow:
190 If omitted, the native name is assumed to be identical to the Eng‐
192 lish name.
193 If class is supplied, it must be the full module name of your cus‐
195 tom locale. If omitted, the locale module is assumed to be a Date‐
196 Time::Locale subclass.
197 Examples:
199 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 # Returns instance of class DateTime::Locale::en_GB_RIDAS
208 my $l = DateTime::Locale->load('en_GB_RIDAS');
209 DateTime::Locale->register
211 ( id => 'hu_HU',
212 en_language => 'Hungarian',
213 en_territory => Hungary',
214 native_language => 'Magyar',
215 native_territory => 'Magyarország',
216 );
217 # Returns instance of class DateTime::Locale::hu_HU
219 my $l = DateTime::Locale->load('hu_HU');
220 DateTime::Locale->register
222 ( id => 'en_GB_RIDAS',
223 name => 'English United Kingdom Ridas custom locale',
224 class => 'Ridas::Locales::CustomGB',
225 );
226 # 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 If you register a locale for an id that already exists, the
232 "replace" parameter must be true or an exception will be thrown.
233 The complete name for a registered locale is generated by joining
235 together the language, territory, and variant components with a
236 single space.
237 This means that in the first example, the complete English and
239 native names for the locale would be "English United Kingdom Ridas
240 Custom Locale", and in the second example the complete English name
241 is "Hungarian Hungary", while the complete native name is "Magyar
242 Magyarország". The locale will be loadable by these complete names
243 (English and native), via the "load()" method.
244
246 These are added in one of two ways:
247 1. Subclass an existing locale implementing only the changes you
249 require.
250 2. Create a completely new locale.
252 In either case the locale MUST be registered before use.
254 Subclass an existing locale.
256 The following example sublasses the United Kingdom English locale to
258 provide different date/time formats:
259 package Ridas::Locale::en_GB_RIDAS1;
261 use strict;
263 use DateTime::Locale::en_GB;
264 @Ridas::Locale::en_GB_RIDAS1::ISA = qw ( DateTime::Locale::en_GB );
266 my $locale_id = 'en_GB_RIDAS1';
268 my $date_formats =
270 {
271 'full' => '%A %{day} %B %{ce_year}',
272 'long' => '%{day} %B %{ce_year}',
273 'medium' => '%{day} %b %{ce_year}',
274 'short' => '%{day}/%m/%y',
275 };
276 my $time_formats =
278 {
279 'full' => '%H h %{minute} %{time_zone_short_name}',
280 'long' => '%{hour12}:%M:%S %p',
281 'medium' => '%{hour12}:%M:%S %p',
282 'short' => '%{hour12}:%M %p',
283 };
284 sub short_date_format { $date_formats{short} }
286 sub medium_date_format { $date_formats{medium} }
287 sub long_date_format { $date_formats{long} }
288 sub full_date_format { $date_formats{full} }
289 sub short_time_format { $time_formats{short} }
291 sub medium_time_format { $time_formats{medium} }
292 sub long_time_format { $time_formats{long} }
293 sub full_time_format { $time_formats{full} }
294 1;
296 Now register it:
298 DateTime::Locale->register
300 ( id => 'en_GB_RIDAS1',
301 # name, territory, and variant as described in register() documentation
303 class => 'Ridas::Locale::en_GB_RIDAS1' );
305 Creating a completely new locale
307 A completely new custom locale must implement the following methods:
309 id
311 month_names
312 month_abbreviations
313 day_names
314 day_abbreviations
315 am_pms
316 eras
317 short_date_format
319 medium_date_format
320 long_date_format
321 full_date_format
322 short_time_format
324 medium_time_format
325 long_time_format
326 full_time_format
327 datetime_format_pattern_order
329 date_parts_order
330 _default_date_format_length
331 _default_time_format_length
332 See "DateTime::Locale::Base" for a description of each method, and take
334 a look at DateTime/Locale/root.pm for an example of a complete imple‐
335 mentation.
336 You are, of course, free to subclass "DateTime::Locale::Base" if you
338 want to, though this is not required.
339 Once created, remember to register it!
341 Of course, you can always do the registration in the module itself, and
343 simply load it before using it.
344
346 All objects that inherit from "DateTime::Locale::Base" will offer cer‐
347 tain methods. All the included locales are "DateTime::Locale::Base"
348 subclasses.
349 The following methods can be used to get information about the locale's
351 id and name.
352 * id
354 The complete locale id, something like "en_US".
355 * language_id
357 The language portion of the id, like "en".
358 * script_id
360 The script portion of the id, like "Hant".
361 * territory_id
363 The territory portion of the id, like "US".
364 * variant_id
366 The variant portion of the id, like "PREEURO".
367 * name
369 The locale's complete name, which always includes at least a lan‐
370 guage component, plus optional territory and variant components.
371 Something like "English United States". The value returned will
372 always be in English.
373 * language
375 * script
376 * territory
377 * variant
378 The relevant component from the locale's complete name, like "Eng‐
379 lish" or "United States".
380 * native_name
382 The locale's complete name in localized form as a UTF-8 string.
383 * native_language
385 * native_script
386 * native_territory
387 * native_variant
388 The relevant component from the locale's complete native name as a
389 UTF-8 string.
390 The following methods all accept a "DateTime.pm" object and return a
392 localized name.
393 * month_name ($dt)
395 * month_abbreviation ($dt)
396 * day_name ($dt)
397 * day_abbreviation ($dt)
398 * am_pm ($dt)
399 The following methods return strings appropriate for the "DateTime.pm"
401 "strftime()" method:
402 * full_date_format
404 * long_date_format
405 * medium_date_format
406 * short_date_format
407 * full_time_format
408 * long_time_format
409 * medium_time_format
410 * short_time_format
411 * full_datetime_format
412 * long_datetime_format
413 * medium_datetime_format
414 * short_datetime_format
415 The following methods deal with the default format lengths:
417 default_date_format_length
419 default_time_format_length
420 These methods return one of "full", "long", "medium", or "short",
421 indicating the current default format length.
422 The default when an object is created is determined by the CLDR
424 locale data.
425 set_default_date_format_length ($length)
427 set_default_time_format_length ($length)
428 These methods accept one of "full", "long", "medium", or "short",
429 indicating the new default format length.
430 The following methods can be used to get the object's raw localization
432 data. If a method returns a reference, altering it will alter the
433 object, so make a copy if you need to do so.
434 * month_names
436 Returns an array reference containing the full names of the months,
437 with January as the first month.
438 * month_abbreviations
440 Returns an array reference containing the abbreviated names of the
441 months, with January as the first month.
442 * month_narrows
444 Returns an array reference containing the narrow names of the
445 months, with January as the first month. Narrow names are the
446 shortest possible names, and may not be unique.
447 * day_names
449 Returns an array reference containing the full names of the days,
450 with Monday as the first day.
451 * day_abbreviations
453 Returns an array reference containing the abbreviated names of the
454 days, with Monday as the first day.
455 * day_narrows
457 Returns an array reference containing the narrow names of the days,
458 with Monday as the first day. Narrow names are the shortest possi‐
459 ble names, and may not be unique.
460 * am_pms
462 Returns an array reference containing the localized forms of "AM"
463 and "PM".
464 * eras
466 Returns an array reference containing the localized forms of "BCE"
467 and "CE".
468 * date_formats
470 Returns a hash reference containing the date formats used for the
471 locale. The hash contains the keys "long", "full", "medium", and
472 "short".
473 * time_formats
475 Returns a hash reference containing the time formats used for the
476 locale. The hash contains the keys "long", "full", "medium", and
477 "short".
478 * date_before_time
480 This returns a boolean value indicating whether or not the date
481 comes before the time when formatting a complete date and time for
482 presentation.
483 * date_parts_order
485 This returns a string indicating the order of the parts of a date
486 that is in the form XX/YY/ZZ. The possible values are "dmy",
487 "mdy", "ydm" and "ymd".
488
490 Please be aware that all locale data has been generated from the CLDR
491 (Common Locale Data Repository) project locales data). The data is
492 currently incomplete, and will contain errors in some locales.
493 When reporting errors in data, please check the primary data sources
495 first, then where necessary report errors directly to the primary
496 source via the CLDR bug report system. See http://unicode.org/cldr/fil‐
497 ing_bug_reports.html for details.
498 Once these errors have been confirmed, please forward the error report
500 and corrections to the DateTime mailing list, datetime@perl.org.
501 Support for this module is provided via the datetime@perl.org email
503 list. See http://lists.perl.org/ for more details.
504
506 Richard Evans <rich@ridas.com>
507 Dave Rolsky <autarch@urth.org>
509 These modules are loosely based on the DateTime::Language modules,
511 which were in turn based on the Date::Language modules from Graham
512 Barr's TimeDate distribution.
513 Thanks to Rick Measham for providing the Java to strftime pattern con‐
515 version routines used during locale generation.
516
518 Copyright (c) 2003 Richard Evans. Copyright (c) 2004-2006 David Rolsky.
519 All rights reserved.
520 This program is free software; you can redistribute it and/or modify it
522 under the same terms as Perl itself.
523 The full text of the license can be found in the LICENSE file included
525 with this module.
526 The locale modules in directory "DateTime/Locale/" have been generated
528 from data provided by the CLDR project, see "Date‐
529 Time/Locale/LICENSE.cldr" for details on the CLDR data's license.
530
532 DateTime::Locale::Base
533 datetime@perl.org mailing list
535 http://datetime.perl.org/
537perl v5.8.8 2007-04-02 DateTime::Locale(3)