1DateTime::Locale(3) User Contributed Perl Documentation DateTime::Locale(3)
2
6 DateTime::Locale - Localization support for DateTime.pm
7
9 version 1.39
10
12 use DateTime::Locale;
13 my $loc = DateTime::Locale->load('en-GB');
15 print $loc->native_name, "\n", $loc->datetime_format_long, "\n";
17 # but mostly just things like ...
19 my $dt = DateTime->now( locale => 'fr' );
21 print "Aujourd'hui le mois est " . $dt->month_name, "\n";
22
24 DateTime::Locale is primarily a factory for the various locale
25 subclasses. It also provides some functions for getting information on
26 all the available locales.
27 If you want to know what methods are available for locale objects, then
29 please read the DateTime::Locale::FromData documentation.
30
32 This module provides the following class methods:
33 DateTime::Locale->load( $locale_code | $locale_name )
35 Returns the locale object for the specified locale code or name - see
36 the DateTime::Locale::Catalog documentation for the list of available
37 codes and names. The name provided may be either the English or native
38 name.
39 If the requested locale is not found, a fallback search takes place to
41 find a suitable replacement.
42 The fallback search order is:
44 {language}-{script}-{territory}
46 {language}-{script}
47 {language}-{territory}-{variant}
48 {language}-{territory}
49 {language}
50 Eg. For the locale code "es-XX-UNKNOWN" the fallback search would be:
52 es-XX-UNKNOWN # Fails - no such locale
54 es-XX # Fails - no such locale
55 es # Found - the es locale is returned as the
56 # closest match to the requested id
57 Eg. For the locale code "es-Latn-XX" the fallback search would be:
59 es-Latn-XX # Fails - no such locale
61 es-Latn # Fails - no such locale
62 es-XX # Fails - no such locale
63 es # Found - the es locale is returned as the
64 # closest match to the requested id
65 If no suitable replacement is found, then an exception is thrown.
67 The loaded locale is cached, so that locale objects may be singletons.
69 Calling "DateTime::Locale->register_from_data",
70 "DateTime::Locale->add_aliases", or "DateTime::Locale->remove_alias"
71 clears the cache.
72 DateTime::Locale->codes
74 my @codes = DateTime::Locale->codes;
75 my $codes = DateTime::Locale->codes;
76 Returns an unsorted list of the available locale codes, or an array
78 reference if called in a scalar context. This list does not include
79 aliases.
80 DateTime::Locale->names
82 my @names = DateTime::Locale->names;
83 my $names = DateTime::Locale->names;
84 Returns an unsorted list of the available locale names in English, or
86 an array reference if called in a scalar context.
87 DateTime::Locale->native_names
89 my @names = DateTime::Locale->native_names;
90 my $names = DateTime::Locale->native_names;
91 Returns an unsorted list of the available locale names in their native
93 language, or an array reference if called in a scalar context. All
94 native names use UTF-8 as appropriate.
95 DateTime::Locale->register_from_data( $locale_data )
97 This method allows you to register a custom locale. The data for the
98 locale is specified as a hash (or hashref) where the keys match the
99 method names given in DateTime::Locale::FromData.
100 If you just want to make some small changes on top of an existing
102 locale you can get that locale's data by calling
103 "$locale->locale_data".
104 Here is an example of making a custom locale based off of "en-US":
106 my $locale = DateTime::Locale->load('en-US');
108 my %data = $locale->locale_data;
109 $data{code} = 'en-US-CUSTOM';
110 $data{time_format_medium} = 'HH:mm:ss';
111 DateTime::Locale->register_from_data(%data);
113 # Prints 18:24:38
115 say DateTime->now( locale => 'en-US-CUSTOM' )->strftime('%X');
116 # Prints 6:24:38 PM
118 say DateTime->now( locale => 'en-US' )->strftime('%X');
119 The keys that should be present in the hash are the same as the
121 accessor methods provided by DateTime::Locale::FromData, except for the
122 following:
123 The *_code methods
125 While you should provide a "code" key, the other methods like
126 "language_code" and "script_code" are determined by parsing the
127 code.
128 All "id" returning methods
130 These are aliases for the corresponding *code methods.
131 "prefers_24_hour_time"
133 This is determined by looking at the short time format to see how
134 it formats hours,
135 "date_format_default" and "time_format_default"
137 These are the corresponding medium formats.
138 "datetime_format" and "datetime_format_default"
140 This is the same as the medium format.
141 "date_formats" and "time_formats"
143 These are calculated as needed.
144 "available_formats"
146 This should be provided as a hashref where the keys are things like
147 "Gy" or "MMMEd" and the values are an actual format like "y G" or
148 "E, MMM d".
149 "locale_data"
151 This is everything you pass in.
152
154 If you are running an application that does pre-forking (for example
155 with Starman), then you should try to load all the locales that you'll
156 need in the parent process. Locales are loaded on-demand, so loading
157 them once in each child will waste memory that could otherwise be
158 shared.
159
161 Please be aware that all locale data has been generated from the CLDR
162 (Common Locale Data Repository) project locales data). The data is
163 incomplete, and may contain errors in some locales.
164 When reporting errors in data, please check the primary data sources
166 first, then where necessary report errors directly to the primary
167 source via the CLDR bug report system. See
168 <http://unicode.org/cldr/filing_bug_reports.html> for details.
169 Once these errors have been confirmed, please forward the error report
171 and corrections to the DateTime mailing list, datetime@perl.org.
172
174 Richard Evans wrote the first version of DateTime::Locale, including
175 the tools to extract the CLDR data.
176
178 datetime@perl.org mailing list
179
181 Bugs may be submitted at
182 <https://github.com/houseabsolute/DateTime-Locale/issues>.
183 There is a mailing list available for users of this distribution,
185 <mailto:datetime@perl.org>.
186
188 The source code repository for DateTime-Locale can be found at
189 <https://github.com/houseabsolute/DateTime-Locale>.
190
192 If you'd like to thank me for the work I've done on this module, please
193 consider making a "donation" to me via PayPal. I spend a lot of free
194 time creating free software, and would appreciate any support you'd
195 care to offer.
196 Please note that I am not suggesting that you must do this in order for
198 me to continue working on this particular software. I will continue to
199 do so, inasmuch as I have in the past, for as long as it interests me.
200 Similarly, a donation made in this way will probably not make me work
202 on this software much more, unless I get so many donations that I can
203 consider working on free software full time (let's all have a chuckle
204 at that together).
205 To donate, log into PayPal and send money to autarch@urth.org, or use
207 the button at <https://houseabsolute.com/foss-donations/>.
208
210 Dave Rolsky <autarch@urth.org>
211
213 • Alexander Pankoff <ccntrq@screenri.de>
214 • James Raspass <jraspass@gmail.com>
216 • Karen Etheridge <ether@cpan.org>
218 • Mohammad S Anwar <mohammad.anwar@yahoo.com>
220 • Ryley Breiddal <rbreiddal@presinet.com>
222 • Sergey Leschenko <Sergey.Leschenko@portaone.com>
224 • yasu47b <nakayamayasuhiro1986@gmail.com>
226
228 This software is copyright (c) 2003 - 2023 by Dave Rolsky.
229 This is free software; you can redistribute it and/or modify it under
231 the same terms as the Perl 5 programming language system itself.
232 The full text of the license can be found in the LICENSE file included
234 with this distribution.
235perl v5.38.0 2023-07-20 DateTime::Locale(3)