lib/Locale/Language.pod

   1
   2 =head1 NAME
   3
   4 Locale::Language - ISO two letter codes for language identification (ISO 639)
   5
   6 =head1 SYNOPSIS
   7
   8     use Locale::Language;
   9
  10     $lang = code2language('en');        # $lang gets 'English'
  11     $code = language2code('French');    # $code gets 'fr'
  12
  13     @codes   = all_language_codes();
  14     @names   = all_language_names();
  15
  16
  17 =head1 DESCRIPTION
  18
  19 The C<Locale::Language> module provides access to the ISO two-letter
  20 codes for identifying languages, as defined in ISO 639. You can either
  21 access the codes via the L<conversion routines> (described below),
  22 or via the two functions which return lists of all language codes or
  23 all language names.
  24
  25
  26 =head1 CONVERSION ROUTINES
  27
  28 There are two conversion routines: C<code2language()> and C<language2code()>.
  29
  30 =over 4
  31
  32 =item code2language()
  33
  34 This function takes a two letter language code and returns a string
  35 which contains the name of the language identified. If the code is
  36 not a valid language code, as defined by ISO 639, then C<undef>
  37 will be returned.
  38
  39     $lang = code2language($code);
  40
  41 =item language2code()
  42
  43 This function takes a language name and returns the corresponding
  44 two letter language code, if such exists.
  45 If the argument could not be identified as a language name,
  46 then C<undef> will be returned.
  47
  48     $code = language2code('French');
  49
  50 The case of the language name is not important.
  51 See the section L<KNOWN BUGS AND LIMITATIONS> below.
  52
  53 =back
  54
  55
  56 =head1 QUERY ROUTINES
  57
  58 There are two function which can be used to obtain a list of all
  59 language codes, or all language names:
  60
  61 =over 4
  62
  63 =item C<all_language_codes()>
  64
  65 Returns a list of all two-letter language codes.
  66 The codes are guaranteed to be all lower-case,
  67 and not in any particular order.
  68
  69 =item C<all_language_names()>
  70
  71 Returns a list of all language names for which there is a corresponding
  72 two-letter language code. The names are capitalised, and not returned
  73 in any particular order.
  74
  75 =back
  76
  77
  78 =head1 EXAMPLES
  79
  80 The following example illustrates use of the C<code2language()> function.
  81 The user is prompted for a language code, and then told the corresponding
  82 language name:
  83
  84     $| = 1;    # turn off buffering
  85
  86     print "Enter language code: ";
  87     chop($code = <STDIN>);
  88     $lang = code2language($code);
  89     if (defined $lang)
  90     {
  91         print "$code = $lang\n";
  92     }
  93     else
  94     {
  95         print "'$code' is not a valid language code!\n";
  96     }
  97
  98 =head1 KNOWN BUGS AND LIMITATIONS
  99
 100 =over 4
 101
 102 =item *
 103
 104 In the current implementation, all data is read in when the
 105 module is loaded, and then held in memory.
 106 A lazy implementation would be more memory friendly.
 107
 108 =item *
 109
 110 Currently just supports the two letter language codes -
 111 there are also three-letter codes, and numbers.
 112 Would these be of any use to anyone?
 113
 114 =back
 115
 116 =head1 SEE ALSO
 117
 118 =over 4
 119
 120 =item Locale::Country
 121
 122 ISO codes for identification of country (ISO 3166).
 123 Supports 2-letter, 3-letter, and numeric country codes.
 124
 125 =item Locale::Script
 126
 127 ISO codes for identification of written scripts (ISO 15924).
 128
 129 =item Locale::Currency
 130
 131 ISO three letter codes for identification of currencies and funds (ISO 4217).
 132
 133 =item ISO 639:1988 (E/F)
 134
 135 Code for the representation of names of languages.
 136
 137 =item http://lcweb.loc.gov/standards/iso639-2/langhome.html
 138
 139 Home page for ISO 639-2.
 140
 141 =back
 142
 143
 144 =head1 AUTHOR
 145
 146 Neil Bowers E<lt>neil@bowers.comE<gt>
 147
 148 =head1 COPYRIGHT
 149
 150 Copyright (C) 2002-2004, Neil Bowers.
 151
 152 Copyright (c) 1997-2001 Canon Research Centre Europe (CRE).
 153
 154 This module is free software; you can redistribute it and/or
 155 modify it under the same terms as Perl itself.
 156
 157 =cut
 158