DateTime::Locale - Localization support for DateTime.pm

NAME

DateTime::Locale - Localization support for DateTime.pm

SYNOPSIS

  use DateTime::Locale;
  my $loc = DateTime::Locale->load('en_GB');
  print $loc->native_locale_name,    "\n",
        $loc->long_datetime_format, "\n";
  # but mostly just things like ...
  my $dt = DateTime->now( locale => 'fr' );
  print "Aujourd'hui le mois est " . $dt->month_name, "\n":

DESCRIPTION

DateTime::Locale is primarily a factory for the various locale subclasses. It also provides some functions for getting information on available locales.

If you want to know what methods are available for locale objects, then please read the DateTime::Locale::Base documentation.

USAGE

This module provides the following class methods:

ADDING CUSTOM LOCALES

These are added in one of two ways:

  1. Subclass an existing locale implementing only the changes you require.

  2. Create a completely new locale.

In either case the locale MUST be registered before use.

Subclass an existing locale.

The following example sublasses the United Kingdom English locale to provide different date/time formats:

  package Ridas::Locale::en_GB_RIDAS1;
  use strict;
  use DateTime::Locale::en_GB;
  @Ridas::Locale::en_GB_RIDAS1::ISA = qw ( DateTime::Locale::en_GB );
  my $locale_id = 'en_GB_RIDAS1';
  my $date_formats =
  {
    'full'   => '%A %{day} %B %{ce_year}',
    'long'   => '%{day} %B %{ce_year}',
    'medium' => '%{day} %b %{ce_year}',
    'short'  => '%{day}/%m/%y',
  };
  my $time_formats =
  {
    'full'   => '%H h  %{minute} %{time_zone_short_name}',
    'long'   => '%{hour12}:%M:%S %p',
    'medium' => '%{hour12}:%M:%S %p',
    'short'  => '%{hour12}:%M %p',
  };
  sub short_date_format  { $date_formats{short} }
  sub medium_date_format { $date_formats{medium} }
  sub long_date_format   { $date_formats{long} }
  sub full_date_format   { $date_formats{full} }
  sub short_time_format  { $time_formats{short} }
  sub medium_time_format { $time_formats{medium} }
  sub long_time_format   { $time_formats{long} }
  sub full_time_format   { $time_formats{full} }
  1;

Now register it:

 DateTime::Locale->register
     ( id       => 'en_GB_RIDAS1',
       # name, territory, and variant as described in register() documentation
       class => 'Ridas::Locale::en_GB_RIDAS1' );

Creating a completely new locale

A completely new custom locale must implement the following methods:

  id
  month_names
  month_abbreviations
  day_names
  day_abbreviations
  am_pms
  eras
  short_date_format
  medium_date_format
  long_date_format
  full_date_format
  short_time_format
  medium_time_format
  long_time_format
  full_time_format
  datetime_format_pattern_order
  date_parts_order
  _default_date_format_length
  _default_time_format_length

See DateTime::Locale::Base for a description of each method, and take a look at DateTime/Locale/root.pm for an example of a complete implementation.

You are, of course, free to subclass DateTime::Locale::Base if you want to, though this is not required.

Once created, remember to register it!

Of course, you can always do the registration in the module itself, and simply load it before using it.

LOCALE OBJECT METHODS

All objects that inherit from DateTime::Locale::Base will offer certain methods. All the included locales are DateTime::Locale::Base subclasses.

The following methods can be used to get information about the locale's id and name.

The following methods all accept a DateTime.pm object and return a localized name.

The following methods return strings appropriate for the DateTime.pm strftime() method:

The following methods deal with the default format lengths:

default_date_format_length
default_time_format_length
These methods return one of ``full'', ``long'', ``medium'', or ``short'', indicating the current default format length.

The default when an object is created is determined by the ICU locale data.

set_default_date_format_length ($length)
set_default_time_format_length ($length)
These methods accept one of ``full'', ``long'', ``medium'', or ``short'', indicating the new default format length.

The following methods can be used to get the object's raw localization data. If a method returns a reference, altering it will alter the object, so make a copy if you need to do so.

SUPPORT

Please be aware that all locale data has been generated from the Common XML Locale Repository project locales (originally ICU locale data). The data is currently incomplete, and will contain errors in some locales.

When reporting errors in data, please check the primary data sources first, then where necessary report errors directly to the primary source via the ICU project's Jitterbug system at http://www.jtcsv.com/cgibin/icu-bugs/

Once these errors have been confirmed, please forward the error report, and corrections to the DateTime mailing list, datetime@perl.org.

Support for this module is provided via the datetime@perl.org email list. See http://lists.perl.org/ for more details.

AUTHORS

Richard Evans <rich@ridas.com>

Dave Rolsky <autarch@urth.org>

These modules are loosely based on the DateTime::Language modules, which were in turn based on the Date::Language modules from Graham Barr's TimeDate distribution.

Thanks to Rick Measham for providing the Java to strftime pattern conversion routines used during locale generation.

COPYRIGHT

Copyright (c) 2003 Richard Evans. Copyright (c) 2004-2005 David Rolsky. All rights reserved.

This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.

The full text of the license can be found in the LICENSE file included with this module.

The locale modules in directory DateTime/Locale/ have been generated from data provided by the Common XML Locale Repository project, see DateTime/Locale/LICENSE.icu for details on the ICU data's license.

SEE ALSO

the DateTime::Locale::Base manpage

datetime@perl.org mailing list

http://datetime.perl.org/

 DateTime::Locale - Localization support for DateTime.pm