# Copyright (c) 1995-2017 Sullivan Beck. All rights reserved.

# This program is free software; you can redistribute it and/or modify it

# under the same terms as Perl itself.

=pod

=head1 NAME

Date::Manip::Lang - language support for Date::Manip

=head1 DESCRIPTION

Date::Manip supports a number of different languages when

parsing dates, and more can be added.

=head1 CURRENT LANGUAGES

Currently, the following languages are supported by Date::Manip.

The version of Date::Manip where they were added is included (so

you can see the minimum version of Date::Manip needed to parse

each).

The language can be chosen by setting the Language config

variable to the name of the language or any of the aliases

included in the table.

All names and aliases are case insensitive.

   Language     Version  Aliases

   English      default  en, en_us

   Catalan      5.43     ca

   Danish       5.41     da

   Dutch        5.32     Nederlands, nl

   Finnish      6.31     fi, fi_fi

   French       5.02     fr, fr_fr

   German       5.31     de, de_de

   Italian      5.35     it, it_it

   Norwegian    6.21     nb, nb_no

   Polish       5.32     pl, pl_pl

   Portuguese   5.34     pt, pt_pt

   Romanian     5.35     ro, ro_ro

   Russian      5.41     ru, ru_ru

   Spanish      5.33     es, es_es

   Swedish      5.05     sv

   Turkish      5.41     tr, tr_tr

=head1 ADDING A LANGUAGE

Adding a language is easily done (if you're fluent in both English

and the other language).  If you want to add a new language, do the

following:

=over 4

=item Language name

When you submit the new language, I'll need the name of the

language (of course) and any common locale names that might

be useful for people to select the language.

For example, if you were creating a Spanish translation (which is not

necessary since it already exists), I would need the following list:

   spanish es es_es

=item Copy the english module

Copy the english.pm file (which is in lib/Date/Manip/Lang in the

Date::Manip distribution) to the new language (i.e. spanish.pm in

this example).

=item Set some variables in the new module

The new module (spanish.pm) will need a few simple modifications.

Change the package name from 'english' to 'spanish'.

Fix the C<@Encodings> lines.  Most languages can be written in more

than one encoding.  The first encoding in the list should be utf-8

and the last should be perl.  Include any other encodings that

should be supported as well.

Set the C<$YearAdded> and C<$LangName> appropriately.

=item Translate the language terms

The data section of the module is fairly straightforward to translate.

Every term is defined in the L<Date::Manip::Lang::english> document

(or in any of the other language module documents), so please

refer to it to find out what each element means.  Then replace the

English version with the new translation.

There are some requirements:

1) Every element should be defined (except for the sephm and sepms

elements which are optional).

2) The module must be written using UTF-8 characters if the language

includes any non-ASCII characters.

3) Each element includes a list of values (different variations of the

element).  In most cases, the order of the values for each element is

not important since they are just used to create a regular expression

for parsing dates, but a few of them are also used to determine printable

values using the C<Date::Manip::Date::printf> method (or the C<UnixDate>

function).  These elements are:

   Element       printf directive

   ampm          %p

   day_abb       %a

   day_char      %v

   day_name      %A

   month_abb     %b

   month_name    %B

   nth           %E

For each of these, the value that should be printed out must be the

first value in the list.

4) When possible, if a language includes characters that are

essentially ASCII characters with a punctuation mark, please include a

variation of the value which is just ASCII with the punctuation

removed.  For example, the spanish name for Saturday in ASCII would be

written sabado, but in reality, the first 'a' has an accent over

it. This word should appear twice... first in full UTF-8 encoding, and

second as all ASCII. If the language (Russian for example) has no

ASCII equivalent, just include the UTF-8 representation.

=back

Feel free to contact me if you have any questions.

=head1 SEE ALSO

L<Date::Manip>        - main module documentation

=head1 LICENSE

This script is free software; you can redistribute it and/or

modify it under the same terms as Perl itself.

=head1 AUTHOR

Sullivan Beck (sbeck@cpan.org)

=cut