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.23
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::Locale::Base
179
180       datetime@perl.org mailing list
181
182       http://datetime.perl.org/
183

SUPPORT

185       Bugs may be submitted at
186       <https://github.com/houseabsolute/DateTime-Locale/issues>.
187
188       There is a mailing list available for users of this distribution,
189       <mailto:datetime@perl.org>.
190
191       I am also usually active on IRC as 'autarch' on "irc://irc.perl.org".
192

SOURCE

194       The source code repository for DateTime-Locale can be found at
195       <https://github.com/houseabsolute/DateTime-Locale>.
196

DONATIONS

198       If you'd like to thank me for the work I've done on this module, please
199       consider making a "donation" to me via PayPal. I spend a lot of free
200       time creating free software, and would appreciate any support you'd
201       care to offer.
202
203       Please note that I am not suggesting that you must do this in order for
204       me to continue working on this particular software. I will continue to
205       do so, inasmuch as I have in the past, for as long as it interests me.
206
207       Similarly, a donation made in this way will probably not make me work
208       on this software much more, unless I get so many donations that I can
209       consider working on free software full time (let's all have a chuckle
210       at that together).
211
212       To donate, log into PayPal and send money to autarch@urth.org, or use
213       the button at <http://www.urth.org/~autarch/fs-donation.html>.
214

AUTHOR

216       Dave Rolsky <autarch@urth.org>
217

CONTRIBUTORS

219       ·   Karen Etheridge <ether@cpan.org>
220
221       ·   Mohammad S Anwar <mohammad.anwar@yahoo.com>
222
223       ·   Ryley Breiddal <rbreiddal@presinet.com>
224
225       ·   Sergey Leschenko <Sergey.Leschenko@portaone.com>
226
227       ·   yasu47b <nakayamayasuhiro1986@gmail.com>
228
230       This software is copyright (c) 2003 - 2018 by Dave Rolsky.
231
232       This is free software; you can redistribute it and/or modify it under
233       the same terms as the Perl 5 programming language system itself.
234
235       The full text of the license can be found in the LICENSE file included
236       with this distribution.
237
238
239
240perl v5.28.1                      2018-10-18               DateTime::Locale(3)
Impressum