locale.pm

1. 记录每个帖子的访问人情况

and will not be returned by querying methods such as C<ids()> or
C<names()>.

 register( id               => $locale_id,
           en_language      => ..., # something like 'English' or 'Afar',

           # All other keys are optional.  These are:
           en_territory => ...,
           en_variant   => ...,

           native_language  => ...,
           native_territory => ...,
           native_variant   => ...,

           # Optional - defaults to DateTime::Locale::$locale_id
           class                => $class_name,

           replace          => $boolean
         )

The locale id and English name are required, and the following formats
should used wherever possible:

 id:   languageId[_territoryId[_variantId]]

 Where:  languageId = Lower case ISO  639 code -
          Always choose 639-1 over 639-2 where possible.

 territoryId = Upper case ISO 3166 code -
               Always choose 3166-1 over 3166-2 where possible.

 variantId = Upper case variant id -
             Basically anything you want, since this is typically the
             component that uniquely identifies a custom locale.

You cannot not use '@' or '=' in locale ids - these are reserved for
future use.  The underscore (_) is the component separator, and should
not be used for any other purpose.

If the "native_*" components are supplied, they must be utf8 encoded
and follow:

If omitted, the native name is assumed to be identical to the English
name.

If class is supplied, it must be the full module name of your custom
locale. If omitted, the locale module is assumed to be a
DateTime::Locale subclass.

Examples:

 DateTime::Locale->register
     ( id => 'en_GB_RIDAS',
       en_language  => 'English',
       en_territory => 'United Kingdom',
       en_variant   => 'Ridas Custom Locale',
     );

 # Returns instance of class DateTime::Locale::en_GB_RIDAS
 my $l = DateTime::Locale->load('en_GB_RIDAS');

 DateTime::Locale->register
     ( id => 'hu_HU',
       en_language  => 'Hungarian',
       en_territory => Hungary',
       native_language  => 'Magyar',
       native_territory => 'Magyarorsz谩g',
     );

 # Returns instance of class DateTime::Locale::hu_HU
 my $l = DateTime::Locale->load('hu_HU');

 DateTime::Locale->register
     ( id    => 'en_GB_RIDAS',
       name  => 'English United Kingdom Ridas custom locale',
       class => 'Ridas::Locales::CustomGB',
     );

 # Returns instance of class Ridas::Locales::CustomGB
 # NOT Ridas::Locales::Custom::en_GB_RIDAS !
 my $l = DateTime::Locale->load('en_GB_RIDAS');

If you a locale for that id already exists, you must specify the
"replace" parameter as true, or an exception will be thrown.

The complete name for a registered locale is generated by joining
together the language, territory, and variant components with a single
space.

This means that in the first example, the complete English and native
names for the locale would be "English United Kingdom Ridas Custom
Locale", and in the second example the complete English name is
"Hungarian Hungary", while the complete native name is "Magyar
Magyarorsz谩g".  The locale will be loadable by these complete names
(English and native), via the C<load()> method.

=back

=head1 ADDING CUSTOM LOCALES

These are added in one of two ways:

=over 4

=item 1.

Subclass an existing locale implementing only the changes you require.

=item 2.

Create a completely new locale.

=back

In either case the locale MUST be registered before use.

=head2 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 =
  [
    "%A %{day} %B %{ce_year}",
    "%{day} %B %{ce_year}",
    "%{day} %b %{ce_year}",
    "%{day}/%m/%y",
  ];

  my $time_formats =
  [
    "%H h  %{minute} %{time_zone_short_name}",
    "%{hour12}:%M:%S %p",
    "%{hour12}:%M:%S %p",
    "%{hour12}:%M %p",
  ];

  sub date_formats { $date_formats }
  sub time_formats { $time_formats }

  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' );

=head2 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
  date_formats
  time_formats
  datetime_format_pattern_order
  date_parts_order
  _default_date_format_length
  _default_time_format_length

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

You are, of course, free to subclass C<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.

=head1 LOCALE OBJECT METHODS

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

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

=over 4

=item * id

The complete locale id, something like "en_US".

=item * language_id

The language portion of the id, like "en".

=item * territory_id

The territory portion of the id, like "US".

=item * variant_id

The variant portion of the id, like "PREEURO".

=item * name

The locale's complete name, which always includes at least a language
component, plus optional territory and variant components.  Something
like "English United States".  The value returned will always be in
English.

=item * language

=item * territory

=item * variant

The relevant component from the locale's complete name, like "English"
or "United States".

=item * native_name

The locale's complete name in localized form as a UTF-8 string.

=item * native_language

=item * native_territory

=item * native_variant

The relevant component from the locale's complete native name as a
UTF-8 string.

=back

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

=over 4

=item * month_name ($dt)

=item * month_abbreviation ($dt)

=item * day_name ($dt)

=item * day_abbreviation ($dt)

=item * am_pm ($dt)

=back

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

=over 4

=item * full_date_format

=item * long_date_format

=item * medium_date_format

=item * short_date_format

=item * full_time_format

=item * long_time_format

=item * medium_time_format

=item * short_time_format

=item * full_datetime_format

=item * long_datetime_format

=item * medium_datetime_format

=item * short_datetime_format

=back

The following methods deal with the default format lengths:

=over 4

=item default_date_format_length

=item 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.

=item set_default_date_format_length ($length)

=item set_default_time_format_length ($length)

These methods return one of "full", "long", "medium", or "short",
indicating the current default format length.

=back

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.

=over 4

=item * month_names

Returns an array reference containing the full names of the months,
with January as the first month.

=item * month_abbreviations

Returns an array reference containing the abbreviated names of the
months, with January as the first month.

=item * day_names

Returns an array reference containing the full names of the days,
with Monday as the first day.

=item * day_abbreviations

Returns an array reference containing the abbreviated names of the
days, with Monday as the first day.

=item * am_pms

Returns an array reference containing the localized forms of "AM" and
"PM".

=item * date_formats

Returns a hash reference containing the date formats used for the
locale.  The hash contains the keys "long", "full", "medium", and
"short".

=item * time_formats

Returns a hash reference containing the time formats used for the
locale.  The hash contains the keys "long", "full", "medium", and
"short".

=item * date_before_time

This returns a boolean value indicating whether or not the date comes
before the time when formatting a complete date and time for
presentation.

=item * date_parts_order

This returns a string indicating the order of the parts of a date that
is in the form XX/YY/ZZ.  The possible values are "dmy", "mdy", "ydm"
and "ymd".

=back

=head1 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 B<is> currently incomplete, and B<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,
[e-mail].

Support for this module is provided via the [e-mail] email
list. See http://lists.perl.org/ for more details.

=head1 AUTHORS

Richard Evans <[e-mail]>

Dave Rolsky <[e-mail]>

These modules are 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.

=head1 COPYRIGHT

Copyright (c) 2003 Richard Evans. 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 C<DateTime/Locale/> have been
generated from data provided by the Common XML Locale Repository
project, see C<DateTime/Locale/LICENSE.icu> for details on the ICU
data's license.

=head1 SEE ALSO

L<DateTime::Locale::Base>

[e-mail] mailing list

http://datetime.perl.org/

=cut