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

NAME

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

VERSION

9       version 1.39
10

SYNOPSIS

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

DESCRIPTION

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
28       If you want to know what methods are available for locale objects, then
29       please read the DateTime::Locale::FromData documentation.
30

USAGE

32       This module provides the following class methods:
33
34   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
40       If the requested locale is not found, a fallback search takes place to
41       find a suitable replacement.
42
43       The fallback search order is:
44
45         {language}-{script}-{territory}
46         {language}-{script}
47         {language}-{territory}-{variant}
48         {language}-{territory}
49         {language}
50
51       Eg. For the locale code "es-XX-UNKNOWN" the fallback search would be:
52
53         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
58       Eg. For the locale code "es-Latn-XX" the fallback search would be:
59
60         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
66       If no suitable replacement is found, then an exception is thrown.
67
68       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
73   DateTime::Locale->codes
74         my @codes = DateTime::Locale->codes;
75         my $codes = DateTime::Locale->codes;
76
77       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
81   DateTime::Locale->names
82         my @names = DateTime::Locale->names;
83         my $names = DateTime::Locale->names;
84
85       Returns an unsorted list of the available locale names in English, or
86       an array reference if called in a scalar context.
87
88   DateTime::Locale->native_names
89         my @names = DateTime::Locale->native_names;
90         my $names = DateTime::Locale->native_names;
91
92       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
96   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
101       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
105       Here is an example of making a custom locale based off of "en-US":
106
107         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
112         DateTime::Locale->register_from_data(%data);
113
114         # Prints 18:24:38
115         say DateTime->now( locale => 'en-US-CUSTOM' )->strftime('%X');
116
117         # Prints 6:24:38 PM
118         say DateTime->now( locale => 'en-US' )->strftime('%X');
119
120       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
124       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
129       All "id" returning methods
130           These are aliases for the corresponding *code methods.
131
132       "prefers_24_hour_time"
133           This is determined by looking at the short time format to see how
134           it formats hours,
135
136       "date_format_default" and "time_format_default"
137           These are the corresponding medium formats.
138
139       "datetime_format" and "datetime_format_default"
140           This is the same as the medium format.
141
142       "date_formats" and "time_formats"
143           These are calculated as needed.
144
145       "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
150       "locale_data"
151           This is everything you pass in.
152

LOADING LOCALES IN A PRE-FORKING SYSTEM

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

CLDR DATA BUGS

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
165       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
170       Once these errors have been confirmed, please forward the error report
171       and corrections to the DateTime mailing list, datetime@perl.org.
172

AUTHOR EMERITUS

174       Richard Evans wrote the first version of DateTime::Locale, including
175       the tools to extract the CLDR data.
176

SEE ALSO

178       datetime@perl.org mailing list
179

SUPPORT

181       Bugs may be submitted at
182       <https://github.com/houseabsolute/DateTime-Locale/issues>.
183
184       There is a mailing list available for users of this distribution,
185       <mailto:datetime@perl.org>.
186

SOURCE

188       The source code repository for DateTime-Locale can be found at
189       <https://github.com/houseabsolute/DateTime-Locale>.
190

DONATIONS

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
197       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
201       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
206       To donate, log into PayPal and send money to autarch@urth.org, or use
207       the button at <https://houseabsolute.com/foss-donations/>.
208

AUTHOR

210       Dave Rolsky <autarch@urth.org>
211

CONTRIBUTORS

213       •   Alexander Pankoff <ccntrq@screenri.de>
214
215       •   James Raspass <jraspass@gmail.com>
216
217       •   Karen Etheridge <ether@cpan.org>
218
219       •   Mohammad S Anwar <mohammad.anwar@yahoo.com>
220
221       •   Ryley Breiddal <rbreiddal@presinet.com>
222
223       •   Sergey Leschenko <Sergey.Leschenko@portaone.com>
224
225       •   yasu47b <nakayamayasuhiro1986@gmail.com>
226
228       This software is copyright (c) 2003 - 2023 by Dave Rolsky.
229
230       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
233       The full text of the license can be found in the LICENSE file included
234       with this distribution.
235
236
237
238perl v5.38.0                      2023-07-20               DateTime::Locale(3)
Impressum