=pod

=head1 NAME

Locale::Language - standard codes for language identification

=head1 SYNOPSIS

   use Locale::Language;

   $lang = code2language('en');        # $lang gets 'English'
   $code = language2code('French');    # $code gets 'fr'

   @codes   = all_language_codes();
   @names   = all_language_names();

=head1 DESCRIPTION

The C<Locale::Language> module provides access to standard codes used
for identifying languages, such as those as defined in ISO 639.

You can either access the codes via the L<conversion routines>
(described below), or via the two functions which return lists of all
language codes or all language names.

All of the routines take an optional additional argument which
specifies the code set to use. If not specified, the default ISO
639 two-letter codes will be used.

=head1 LANGUAGE NAMES

Locale::Language supports variant names for countries.

Language names come from the standards, but common aliases are included
(and others may be added). If you have a common alias for a language,
let me know and I'll add it, with some restrictions.

=head1 SUPPORTED CODE SETS

There are many different code sets you can use for identifying
languages. The ones currently supported are:

=over 4

=item B<alpha-2>

This is the set of two-letter (lowercase) codes from ISO 639, such
as 'he' for Hebrew.

This code set is identified with the symbol C<LOCALE_LANG_ALPHA_2>.

If no code set is specified in a call to any of the routines
described below, it will default to this code set.

=item B<alpha-3>

This is the set of three-letter (lowercase) bibliographic codes from
ISO 639, such as 'heb' for Hebrew.

This code set is identified with the symbol C<LOCALE_LANG_ALPHA_3>.

=item B<term>

This is the set of three-letter (lowercase) terminologic codes from
ISO 639.

This code set is identified with the symbol C<LOCALE_LANG_TERM>.

=back

=head1 CONVERSION ROUTINES

There are three conversion routines: C<code2language()>, C<language2code()>,
and C<language_code2code()>.

=over 4

=item code2language(CODE, [CODESET])

This function takes a two letter language code and returns a string
which contains the name of the language identified. If the code is not
a valid language code, as defined by ISO 639, then C<undef> will be
returned.

   $lang = code2language($code);

=item language2code(NAME, [CODESET])

This function takes a language name and returns the corresponding two
letter language code, if such exists.  If the argument could not be
identified as a language name, then C<undef> will be returned.

   $code = language2code('French');

The case of the language name is not important.

=item language_code2code( CODE, CODESET, CODESET )

This function takes a language code from one code set, and returns the
corresponding code from another code set.

Both CODESETs must be explicitly entered.

   language_code2code('aym', LOCALE_LANG_ALPHA_3,
                     LOCALE_LANG_ALPHA_2);
      => 'ay'

If the code passed is not a valid language code in the first code set,
or if there isn't a code for the corresponding language in the second
code set, then C<undef> will be returned.

=back

=head1 QUERY ROUTINES

There are two function which can be used to obtain a list of all
language codes, or all language names:

=over 4

=item all_language_codes( [CODESET] )

Returns a list of all language codes in the given code set.

=item C<all_language_names()>

Returns a list of all language names for which there is a corresponding
language code. The names returned are the names specified in the
standard.

=back

=head1 EXAMPLES

The following example illustrates use of the C<code2language()>
function.  The user is prompted for a language code, and then told the
corresponding language name:

    $| = 1;    # turn off buffering

    print "Enter language code: ";
    chop($code = <STDIN>);
    $lang = code2language($code);
    if (defined $lang) {
        print "$code = $lang\n";
    } else {
        print "'$code' is not a valid language code!\n";
    }

=head1 KNOWN BUGS AND LIMITATIONS

=over 4

=item *

Currently, language names are in pure ASCII. I plan to relax that in the
future.

=item *

I do not yet support the codes for ISO 639-3 (which has codes for all
languages living or dead). I may add support in a future version.

=back

=head1 SEE ALSO

=over 4

=item Locale::Codes

=item Locale::Constants

=item http://www.loc.gov/standards/iso639-2/

Source of the ISO 639 codes.

=back

=head1 AUTHOR

See Locale::Codes for full author history.

Currently maintained by Sullivan Beck (sbeck@cpan.org).

=head1 COPYRIGHT

   Copyright (c) 1997-2001 Canon Research Centre Europe (CRE).
   Copyright (c) 2001-2010 Neil Bowers
   Copyright (c) 2010-2010 Sullivan Beck

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

=cut
