DateTime::Locale->load( $locale_code | $locale_name )

Returns the locale object for the specified locale code or name - see the "DateTime::Locale::Catalog" documentation for the list of available codes and names. The name provided may be either the English or native name.

If the requested locale is not found, a fallback search takes place to find a suitable replacement.

The fallback search order is:

  {language}-{script}-{territory}
  {language}-{script}
  {language}-{territory}-{variant}
  {language}-{territory}
  {language}

Eg. For the locale code "es-XX-UNKNOWN" the fallback search would be:

  es-XX-UNKNOWN   # Fails - no such locale
  es-XX           # Fails - no such locale
  es              # Found - the es locale is returned as the
                  # closest match to the requested id

Eg. For the locale code "es-Latn-XX" the fallback search would be:

  es-Latn-XX      # Fails - no such locale
  es-Latn         # Fails - no such locale
  es-XX           # Fails - no such locale
  es              # Found - the es locale is returned as the
                  # closest match to the requested id

If no suitable replacement is found, then an exception is thrown.

The loaded locale is cached, so that locale objects may be singletons. Calling "DateTime::Locale->register_from_data", "DateTime::Locale->add_aliases", or "DateTime::Locale->remove_alias" clears the cache.

DateTime::Locale->codes

  my @codes = DateTime::Locale->codes;
  my $codes = DateTime::Locale->codes;

Returns an unsorted list of the available locale codes, or an array reference if called in a scalar context. This list does not include aliases.

DateTime::Locale->names

  my @names = DateTime::Locale->names;
  my $names = DateTime::Locale->names;

Returns an unsorted list of the available locale names in English, or an array reference if called in a scalar context.

DateTime::Locale->native_names

  my @names = DateTime::Locale->native_names;
  my $names = DateTime::Locale->native_names;

Returns an unsorted list of the available locale names in their native language, or an array reference if called in a scalar context. All native names use UTF-8 as appropriate.

DateTime::Locale->register_from_data( $locale_data )

This method allows you to register a custom locale. The data for the locale is specified as a hash (or hashref) where the keys match the method names given in "DateTime::Locale::FromData".

If you just want to make some small changes on top of an existing locale you can get that locale's data by calling "$locale->locale_data".

Here is an example of making a custom locale based off of "en-US":

  my $locale = DateTime::Locale->load('en-US');
  my %data   = $locale->locale_data;
  $data{code}               = 'en-US-CUSTOM';
  $data{time_format_medium} = 'HH:mm:ss';
  DateTime::Locale->register_from_data(%data);
  # Prints 18:24:38
  say DateTime->now( locale => 'en-US-CUSTOM' )->strftime('%X');
  # Prints 6:24:38 PM
  say DateTime->now( locale => 'en-US' )->strftime('%X');

The keys that should be present in the hash are the same as the accessor methods provided by DateTime::Locale::FromData, except for the following:

The *_code methods

While you should provide a "code" key, the other methods like "language_code" and "script_code" are determined by parsing the code.

All "id" returning methods

These are aliases for the corresponding *code methods.

"prefers_24_hour_time"

This is determined by looking at the short time format to see how it formats hours,

"date_format_default" and "time_format_default"

These are the corresponding medium formats.

"datetime_format" and "datetime_format_default"

This is the same as the medium format.

"date_formats" and "time_formats"

These are calculated as needed.

"available_formats"

This should be provided as a hashref where the keys are things like "Gy" or "MMMEd" and the values are an actual format like "y G" or "E, MMM d".

"locale_data"

This is everything you pass in.