| 1 |
.\" -*- mode: troff; coding: utf-8 -*- |
| 2 |
.\" Automatically generated by Pod::Man 5.0102 (Pod::Simple 3.45) |
| 3 |
.\" |
| 4 |
.\" Standard preamble: |
| 5 |
.\" ======================================================================== |
| 6 |
.de Sp \" Vertical space (when we can't use .PP) |
| 7 |
.if t .sp .5v |
| 8 |
.if n .sp |
| 9 |
.. |
| 10 |
.de Vb \" Begin verbatim text |
| 11 |
.ft CW |
| 12 |
.nf |
| 13 |
.ne \\$1 |
| 14 |
.. |
| 15 |
.de Ve \" End verbatim text |
| 16 |
.ft R |
| 17 |
.fi |
| 18 |
.. |
| 19 |
.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. |
| 20 |
.ie n \{\ |
| 21 |
. ds C` "" |
| 22 |
. ds C' "" |
| 23 |
'br\} |
| 24 |
.el\{\ |
| 25 |
. ds C` |
| 26 |
. ds C' |
| 27 |
'br\} |
| 28 |
.\" |
| 29 |
.\" Escape single quotes in literal strings from groff's Unicode transform. |
| 30 |
.ie \n(.g .ds Aq \(aq |
| 31 |
.el .ds Aq ' |
| 32 |
.\" |
| 33 |
.\" If the F register is >0, we'll generate index entries on stderr for |
| 34 |
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index |
| 35 |
.\" entries marked with X<> in POD. Of course, you'll have to process the |
| 36 |
.\" output yourself in some meaningful fashion. |
| 37 |
.\" |
| 38 |
.\" Avoid warning from groff about undefined register 'F'. |
| 39 |
.de IX |
| 40 |
.. |
| 41 |
.nr rF 0 |
| 42 |
.if \n(.g .if rF .nr rF 1 |
| 43 |
.if (\n(rF:(\n(.g==0)) \{\ |
| 44 |
. if \nF \{\ |
| 45 |
. de IX |
| 46 |
. tm Index:\\$1\t\\n%\t"\\$2" |
| 47 |
.. |
| 48 |
. if !\nF==2 \{\ |
| 49 |
. nr % 0 |
| 50 |
. nr F 2 |
| 51 |
. \} |
| 52 |
. \} |
| 53 |
.\} |
| 54 |
.rr rF |
| 55 |
.\" ======================================================================== |
| 56 |
.\" |
| 57 |
.IX Title "I18N::LangTags 3perl" |
| 58 |
.TH I18N::LangTags 3perl 2025-11-16 "perl v5.40.1" "Perl Programmers Reference Guide" |
| 59 |
.\" For nroff, turn off justification. Always turn off hyphenation; it makes |
| 60 |
.\" way too many mistakes in technical documents. |
| 61 |
.if n .ad l |
| 62 |
.nh |
| 63 |
.SH NAME |
| 64 |
I18N::LangTags \- functions for dealing with RFC3066\-style language tags |
| 65 |
.SH SYNOPSIS |
| 66 |
.IX Header "SYNOPSIS" |
| 67 |
.Vb 1 |
| 68 |
\& use I18N::LangTags(); |
| 69 |
.Ve |
| 70 |
.PP |
| 71 |
\&...or specify whichever of those functions you want to import, like so: |
| 72 |
.PP |
| 73 |
.Vb 1 |
| 74 |
\& use I18N::LangTags qw(implicate_supers similarity_language_tag); |
| 75 |
.Ve |
| 76 |
.PP |
| 77 |
All the exportable functions are listed below \-\- you're free to import |
| 78 |
only some, or none at all. By default, none are imported. If you |
| 79 |
say: |
| 80 |
.PP |
| 81 |
.Vb 1 |
| 82 |
\& use I18N::LangTags qw(:ALL) |
| 83 |
.Ve |
| 84 |
.PP |
| 85 |
\&...then all are exported. (This saves you from having to use |
| 86 |
something less obvious like \f(CW\*(C`use I18N::LangTags qw(/./)\*(C'\fR.) |
| 87 |
.PP |
| 88 |
If you don't import any of these functions, assume a \f(CW&I18N::LangTags::\fR |
| 89 |
in front of all the function names in the following examples. |
| 90 |
.SH DESCRIPTION |
| 91 |
.IX Header "DESCRIPTION" |
| 92 |
Language tags are a formalism, described in RFC 3066 (obsoleting |
| 93 |
1766), for declaring what language form (language and possibly |
| 94 |
dialect) a given chunk of information is in. |
| 95 |
.PP |
| 96 |
This library provides functions for common tasks involving language |
| 97 |
tags as they are needed in a variety of protocols and applications. |
| 98 |
.PP |
| 99 |
Please see the "See Also" references for a thorough explanation |
| 100 |
of how to correctly use language tags. |
| 101 |
.IP \(bu 4 |
| 102 |
the function is_language_tag($lang1) |
| 103 |
.Sp |
| 104 |
Returns true iff \f(CW$lang1\fR is a formally valid language tag. |
| 105 |
.Sp |
| 106 |
.Vb 3 |
| 107 |
\& is_language_tag("fr") is TRUE |
| 108 |
\& is_language_tag("x\-jicarilla") is FALSE |
| 109 |
\& (Subtags can be 8 chars long at most \-\- \*(Aqjicarilla\*(Aq is 9) |
| 110 |
\& |
| 111 |
\& is_language_tag("sgn\-US") is TRUE |
| 112 |
\& (That\*(Aqs American Sign Language) |
| 113 |
\& |
| 114 |
\& is_language_tag("i\-Klikitat") is TRUE |
| 115 |
\& (True without regard to the fact noone has actually |
| 116 |
\& registered Klikitat \-\- it\*(Aqs a formally valid tag) |
| 117 |
\& |
| 118 |
\& is_language_tag("fr\-patois") is TRUE |
| 119 |
\& (Formally valid \-\- altho descriptively weak!) |
| 120 |
\& |
| 121 |
\& is_language_tag("Spanish") is FALSE |
| 122 |
\& is_language_tag("french\-patois") is FALSE |
| 123 |
\& (No good \-\- first subtag has to match |
| 124 |
\& /^([xXiI]|[a\-zA\-Z]{2,3})$/ \-\- see RFC3066) |
| 125 |
\& |
| 126 |
\& is_language_tag("x\-borg\-prot2532") is TRUE |
| 127 |
\& (Yes, subtags can contain digits, as of RFC3066) |
| 128 |
.Ve |
| 129 |
.IP \(bu 4 |
| 130 |
the function extract_language_tags($whatever) |
| 131 |
.Sp |
| 132 |
Returns a list of whatever looks like formally valid language tags |
| 133 |
in \f(CW$whatever\fR. Not very smart, so don't get too creative with |
| 134 |
what you want to feed it. |
| 135 |
.Sp |
| 136 |
.Vb 2 |
| 137 |
\& extract_language_tags("fr, fr\-ca, i\-mingo") |
| 138 |
\& returns: (\*(Aqfr\*(Aq, \*(Aqfr\-ca\*(Aq, \*(Aqi\-mingo\*(Aq) |
| 139 |
\& |
| 140 |
\& extract_language_tags("It\*(Aqs like this: I\*(Aqm in fr \-\- French!") |
| 141 |
\& returns: (\*(AqIt\*(Aq, \*(Aqin\*(Aq, \*(Aqfr\*(Aq) |
| 142 |
\& (So don\*(Aqt just feed it any old thing.) |
| 143 |
.Ve |
| 144 |
.Sp |
| 145 |
The output is untainted. If you don't know what tainting is, |
| 146 |
don't worry about it. |
| 147 |
.IP \(bu 4 |
| 148 |
the function same_language_tag($lang1, \f(CW$lang2\fR) |
| 149 |
.Sp |
| 150 |
Returns true iff \f(CW$lang1\fR and \f(CW$lang2\fR are acceptable variant tags |
| 151 |
representing the same language-form. |
| 152 |
.Sp |
| 153 |
.Vb 10 |
| 154 |
\& same_language_tag(\*(Aqx\-kadara\*(Aq, \*(Aqi\-kadara\*(Aq) is TRUE |
| 155 |
\& (The x/i\- alternation doesn\*(Aqt matter) |
| 156 |
\& same_language_tag(\*(AqX\-KADARA\*(Aq, \*(Aqi\-kadara\*(Aq) is TRUE |
| 157 |
\& (...and neither does case) |
| 158 |
\& same_language_tag(\*(Aqen\*(Aq, \*(Aqen\-US\*(Aq) is FALSE |
| 159 |
\& (all\-English is not the SAME as US English) |
| 160 |
\& same_language_tag(\*(Aqx\-kadara\*(Aq, \*(Aqx\-kadar\*(Aq) is FALSE |
| 161 |
\& (these are totally unrelated tags) |
| 162 |
\& same_language_tag(\*(Aqno\-bok\*(Aq, \*(Aqnb\*(Aq) is TRUE |
| 163 |
\& (no\-bok is a legacy tag for nb (Norwegian Bokmal)) |
| 164 |
.Ve |
| 165 |
.Sp |
| 166 |
\&\f(CW\*(C`same_language_tag\*(C'\fR works by just seeing whether |
| 167 |
\&\f(CWencode_language_tag($lang1)\fR is the same as |
| 168 |
\&\f(CWencode_language_tag($lang2)\fR. |
| 169 |
.Sp |
| 170 |
(Yes, I know this function is named a bit oddly. Call it historic |
| 171 |
reasons.) |
| 172 |
.IP \(bu 4 |
| 173 |
the function similarity_language_tag($lang1, \f(CW$lang2\fR) |
| 174 |
.Sp |
| 175 |
Returns an integer representing the degree of similarity between |
| 176 |
tags \f(CW$lang1\fR and \f(CW$lang2\fR (the order of which does not matter), where |
| 177 |
similarity is the number of common elements on the left, |
| 178 |
without regard to case and to x/i\- alternation. |
| 179 |
.Sp |
| 180 |
.Vb 4 |
| 181 |
\& similarity_language_tag(\*(Aqfr\*(Aq, \*(Aqfr\-ca\*(Aq) is 1 |
| 182 |
\& (one element in common) |
| 183 |
\& similarity_language_tag(\*(Aqfr\-ca\*(Aq, \*(Aqfr\-FR\*(Aq) is 1 |
| 184 |
\& (one element in common) |
| 185 |
\& |
| 186 |
\& similarity_language_tag(\*(Aqfr\-CA\-joual\*(Aq, |
| 187 |
\& \*(Aqfr\-CA\-PEI\*(Aq) is 2 |
| 188 |
\& similarity_language_tag(\*(Aqfr\-CA\-joual\*(Aq, \*(Aqfr\-CA\*(Aq) is 2 |
| 189 |
\& (two elements in common) |
| 190 |
\& |
| 191 |
\& similarity_language_tag(\*(Aqx\-kadara\*(Aq, \*(Aqi\-kadara\*(Aq) is 1 |
| 192 |
\& (x/i\- doesn\*(Aqt matter) |
| 193 |
\& |
| 194 |
\& similarity_language_tag(\*(Aqen\*(Aq, \*(Aqx\-kadar\*(Aq) is 0 |
| 195 |
\& similarity_language_tag(\*(Aqx\-kadara\*(Aq, \*(Aqx\-kadar\*(Aq) is 0 |
| 196 |
\& (unrelated tags \-\- no similarity) |
| 197 |
\& |
| 198 |
\& similarity_language_tag(\*(Aqi\-cree\-syllabic\*(Aq, |
| 199 |
\& \*(Aqi\-cherokee\-syllabic\*(Aq) is 0 |
| 200 |
\& (no B<leftmost> elements in common!) |
| 201 |
.Ve |
| 202 |
.IP \(bu 4 |
| 203 |
the function is_dialect_of($lang1, \f(CW$lang2\fR) |
| 204 |
.Sp |
| 205 |
Returns true iff language tag \f(CW$lang1\fR represents a subform of |
| 206 |
language tag \f(CW$lang2\fR. |
| 207 |
.Sp |
| 208 |
\&\fBGet the order right! It doesn't work the other way around!\fR |
| 209 |
.Sp |
| 210 |
.Vb 2 |
| 211 |
\& is_dialect_of(\*(Aqen\-US\*(Aq, \*(Aqen\*(Aq) is TRUE |
| 212 |
\& (American English IS a dialect of all\-English) |
| 213 |
\& |
| 214 |
\& is_dialect_of(\*(Aqfr\-CA\-joual\*(Aq, \*(Aqfr\-CA\*(Aq) is TRUE |
| 215 |
\& is_dialect_of(\*(Aqfr\-CA\-joual\*(Aq, \*(Aqfr\*(Aq) is TRUE |
| 216 |
\& (Joual is a dialect of (a dialect of) French) |
| 217 |
\& |
| 218 |
\& is_dialect_of(\*(Aqen\*(Aq, \*(Aqen\-US\*(Aq) is FALSE |
| 219 |
\& (all\-English is a NOT dialect of American English) |
| 220 |
\& |
| 221 |
\& is_dialect_of(\*(Aqfr\*(Aq, \*(Aqen\-CA\*(Aq) is FALSE |
| 222 |
\& |
| 223 |
\& is_dialect_of(\*(Aqen\*(Aq, \*(Aqen\*(Aq ) is TRUE |
| 224 |
\& is_dialect_of(\*(Aqen\-US\*(Aq, \*(Aqen\-US\*(Aq) is TRUE |
| 225 |
\& (B<Note:> these are degenerate cases) |
| 226 |
\& |
| 227 |
\& is_dialect_of(\*(Aqi\-mingo\-tom\*(Aq, \*(Aqx\-Mingo\*(Aq) is TRUE |
| 228 |
\& (the x/i thing doesn\*(Aqt matter, nor does case) |
| 229 |
\& |
| 230 |
\& is_dialect_of(\*(Aqnn\*(Aq, \*(Aqno\*(Aq) is TRUE |
| 231 |
\& (because \*(Aqnn\*(Aq (New Norse) is aliased to \*(Aqno\-nyn\*(Aq, |
| 232 |
\& as a special legacy case, and \*(Aqno\-nyn\*(Aq is a |
| 233 |
\& subform of \*(Aqno\*(Aq (Norwegian)) |
| 234 |
.Ve |
| 235 |
.IP \(bu 4 |
| 236 |
the function super_languages($lang1) |
| 237 |
.Sp |
| 238 |
Returns a list of language tags that are superordinate tags to \f(CW$lang1\fR |
| 239 |
\&\-\- it gets this by removing subtags from the end of \f(CW$lang1\fR until |
| 240 |
nothing (or just "i" or "x") is left. |
| 241 |
.Sp |
| 242 |
.Vb 1 |
| 243 |
\& super_languages("fr\-CA\-joual") is ("fr\-CA", "fr") |
| 244 |
\& |
| 245 |
\& super_languages("en\-AU") is ("en") |
| 246 |
\& |
| 247 |
\& super_languages("en") is empty\-list, () |
| 248 |
\& |
| 249 |
\& super_languages("i\-cherokee") is empty\-list, () |
| 250 |
\& ...not ("i"), which would be illegal as well as pointless. |
| 251 |
.Ve |
| 252 |
.Sp |
| 253 |
If \f(CW$lang1\fR is not a valid language tag, returns empty-list in |
| 254 |
a list context, undef in a scalar context. |
| 255 |
.Sp |
| 256 |
A notable and rather unavoidable problem with this method: |
| 257 |
"x\-mingo-tom" has an "x" because the whole tag isn't an |
| 258 |
IANA-registered tag \-\- but super_languages('x\-mingo\-tom') is |
| 259 |
('x\-mingo') \-\- which isn't really right, since 'i\-mingo' is |
| 260 |
registered. But this module has no way of knowing that. (But note |
| 261 |
that same_language_tag('x\-mingo', 'i\-mingo') is TRUE.) |
| 262 |
.Sp |
| 263 |
More importantly, you assume \fIat your peril\fR that superordinates of |
| 264 |
\&\f(CW$lang1\fR are mutually intelligible with \f(CW$lang1\fR. Consider this |
| 265 |
carefully. |
| 266 |
.IP \(bu 4 |
| 267 |
the function locale2language_tag($locale_identifier) |
| 268 |
.Sp |
| 269 |
This takes a locale name (like "en", "en_US", or "en_US.ISO8859\-1") |
| 270 |
and maps it to a language tag. If it's not mappable (as with, |
| 271 |
notably, "C" and "POSIX"), this returns empty-list in a list context, |
| 272 |
or undef in a scalar context. |
| 273 |
.Sp |
| 274 |
.Vb 1 |
| 275 |
\& locale2language_tag("en") is "en" |
| 276 |
\& |
| 277 |
\& locale2language_tag("en_US") is "en\-US" |
| 278 |
\& |
| 279 |
\& locale2language_tag("en_US.ISO8859\-1") is "en\-US" |
| 280 |
\& |
| 281 |
\& locale2language_tag("C") is undef or () |
| 282 |
\& |
| 283 |
\& locale2language_tag("POSIX") is undef or () |
| 284 |
\& |
| 285 |
\& locale2language_tag("POSIX") is undef or () |
| 286 |
.Ve |
| 287 |
.Sp |
| 288 |
I'm not totally sure that locale names map satisfactorily to language |
| 289 |
tags. Think REAL hard about how you use this. YOU HAVE BEEN WARNED. |
| 290 |
.Sp |
| 291 |
The output is untainted. If you don't know what tainting is, |
| 292 |
don't worry about it. |
| 293 |
.IP \(bu 4 |
| 294 |
the function encode_language_tag($lang1) |
| 295 |
.Sp |
| 296 |
This function, if given a language tag, returns an encoding of it such |
| 297 |
that: |
| 298 |
.Sp |
| 299 |
* tags representing different languages never get the same encoding. |
| 300 |
.Sp |
| 301 |
* tags representing the same language always get the same encoding. |
| 302 |
.Sp |
| 303 |
* an encoding of a formally valid language tag always is a string |
| 304 |
value that is defined, has length, and is true if considered as a |
| 305 |
boolean. |
| 306 |
.Sp |
| 307 |
Note that the encoding itself is \fBnot\fR a formally valid language tag. |
| 308 |
Note also that you cannot, currently, go from an encoding back to a |
| 309 |
language tag that it's an encoding of. |
| 310 |
.Sp |
| 311 |
Note also that you \fBmust\fR consider the encoded value as atomic; i.e., |
| 312 |
you should not consider it as anything but an opaque, unanalysable |
| 313 |
string value. (The internals of the encoding method may change in |
| 314 |
future versions, as the language tagging standard changes over time.) |
| 315 |
.Sp |
| 316 |
\&\f(CW\*(C`encode_language_tag\*(C'\fR returns undef if given anything other than a |
| 317 |
formally valid language tag. |
| 318 |
.Sp |
| 319 |
The reason \f(CW\*(C`encode_language_tag\*(C'\fR exists is because different language |
| 320 |
tags may represent the same language; this is normally treatable with |
| 321 |
\&\f(CW\*(C`same_language_tag\*(C'\fR, but consider this situation: |
| 322 |
.Sp |
| 323 |
You have a data file that expresses greetings in different languages. |
| 324 |
Its format is "[language tag]=[how to say 'Hello']", like: |
| 325 |
.Sp |
| 326 |
.Vb 3 |
| 327 |
\& en\-US=Hiho |
| 328 |
\& fr=Bonjour |
| 329 |
\& i\-mingo=Hau\*(Aq |
| 330 |
.Ve |
| 331 |
.Sp |
| 332 |
And suppose you write a program that reads that file and then runs as |
| 333 |
a daemon, answering client requests that specify a language tag and |
| 334 |
then expect the string that says how to greet in that language. So an |
| 335 |
interaction looks like: |
| 336 |
.Sp |
| 337 |
.Vb 2 |
| 338 |
\& greeting\-client asks: fr |
| 339 |
\& greeting\-server answers: Bonjour |
| 340 |
.Ve |
| 341 |
.Sp |
| 342 |
So far so good. But suppose the way you're implementing this is: |
| 343 |
.Sp |
| 344 |
.Vb 9 |
| 345 |
\& my %greetings; |
| 346 |
\& die unless open(IN, "<", "in.dat"); |
| 347 |
\& while(<IN>) { |
| 348 |
\& chomp; |
| 349 |
\& next unless /^([^=]+)=(.+)/s; |
| 350 |
\& my($lang, $expr) = ($1, $2); |
| 351 |
\& $greetings{$lang} = $expr; |
| 352 |
\& } |
| 353 |
\& close(IN); |
| 354 |
.Ve |
| 355 |
.Sp |
| 356 |
at which point \f(CW%greetings\fR has the contents: |
| 357 |
.Sp |
| 358 |
.Vb 3 |
| 359 |
\& "en\-US" => "Hiho" |
| 360 |
\& "fr" => "Bonjour" |
| 361 |
\& "i\-mingo" => "Hau\*(Aq" |
| 362 |
.Ve |
| 363 |
.Sp |
| 364 |
And suppose then that you answer client requests for language \f(CW$wanted\fR |
| 365 |
by just looking up \f(CW$greetings\fR{$wanted}. |
| 366 |
.Sp |
| 367 |
If the client asks for "fr", that will look up successfully in |
| 368 |
\&\f(CW%greetings\fR, to the value "Bonjour". And if the client asks for |
| 369 |
"i\-mingo", that will look up successfully in \f(CW%greetings\fR, to the value |
| 370 |
"Hau'". |
| 371 |
.Sp |
| 372 |
But if the client asks for "i\-Mingo" or "x\-mingo", or "Fr", then the |
| 373 |
lookup in \f(CW%greetings\fR fails. That's the Wrong Thing. |
| 374 |
.Sp |
| 375 |
You could instead do lookups on \f(CW$wanted\fR with: |
| 376 |
.Sp |
| 377 |
.Vb 8 |
| 378 |
\& use I18N::LangTags qw(same_language_tag); |
| 379 |
\& my $response = \*(Aq\*(Aq; |
| 380 |
\& foreach my $l2 (keys %greetings) { |
| 381 |
\& if(same_language_tag($wanted, $l2)) { |
| 382 |
\& $response = $greetings{$l2}; |
| 383 |
\& last; |
| 384 |
\& } |
| 385 |
\& } |
| 386 |
.Ve |
| 387 |
.Sp |
| 388 |
But that's rather inefficient. A better way to do it is to start your |
| 389 |
program with: |
| 390 |
.Sp |
| 391 |
.Vb 12 |
| 392 |
\& use I18N::LangTags qw(encode_language_tag); |
| 393 |
\& my %greetings; |
| 394 |
\& die unless open(IN, "<", "in.dat"); |
| 395 |
\& while(<IN>) { |
| 396 |
\& chomp; |
| 397 |
\& next unless /^([^=]+)=(.+)/s; |
| 398 |
\& my($lang, $expr) = ($1, $2); |
| 399 |
\& $greetings{ |
| 400 |
\& encode_language_tag($lang) |
| 401 |
\& } = $expr; |
| 402 |
\& } |
| 403 |
\& close(IN); |
| 404 |
.Ve |
| 405 |
.Sp |
| 406 |
and then just answer client requests for language \f(CW$wanted\fR by just |
| 407 |
looking up |
| 408 |
.Sp |
| 409 |
.Vb 1 |
| 410 |
\& $greetings{encode_language_tag($wanted)} |
| 411 |
.Ve |
| 412 |
.Sp |
| 413 |
And that does the Right Thing. |
| 414 |
.IP \(bu 4 |
| 415 |
the function alternate_language_tags($lang1) |
| 416 |
.Sp |
| 417 |
This function, if given a language tag, returns all language tags that |
| 418 |
are alternate forms of this language tag. (I.e., tags which refer to |
| 419 |
the same language.) This is meant to handle legacy tags caused by |
| 420 |
the minor changes in language tag standards over the years; and |
| 421 |
the x\-/i\- alternation is also dealt with. |
| 422 |
.Sp |
| 423 |
Note that this function does \fInot\fR try to equate new (and never-used, |
| 424 |
and unusable) |
| 425 |
ISO639\-2 three-letter tags to old (and still in use) ISO639\-1 |
| 426 |
two-letter equivalents \-\- like "ara" \-> "ar" \-\- because |
| 427 |
"ara" has \fInever\fR been in use as an Internet language tag, |
| 428 |
and RFC 3066 stipulates that it never should be, since a shorter |
| 429 |
tag ("ar") exists. |
| 430 |
.Sp |
| 431 |
Examples: |
| 432 |
.Sp |
| 433 |
.Vb 10 |
| 434 |
\& alternate_language_tags(\*(Aqno\-bok\*(Aq) is (\*(Aqnb\*(Aq) |
| 435 |
\& alternate_language_tags(\*(Aqnb\*(Aq) is (\*(Aqno\-bok\*(Aq) |
| 436 |
\& alternate_language_tags(\*(Aqhe\*(Aq) is (\*(Aqiw\*(Aq) |
| 437 |
\& alternate_language_tags(\*(Aqiw\*(Aq) is (\*(Aqhe\*(Aq) |
| 438 |
\& alternate_language_tags(\*(Aqi\-hakka\*(Aq) is (\*(Aqzh\-hakka\*(Aq, \*(Aqx\-hakka\*(Aq) |
| 439 |
\& alternate_language_tags(\*(Aqzh\-hakka\*(Aq) is (\*(Aqi\-hakka\*(Aq, \*(Aqx\-hakka\*(Aq) |
| 440 |
\& alternate_language_tags(\*(Aqen\*(Aq) is () |
| 441 |
\& alternate_language_tags(\*(Aqx\-mingo\-tom\*(Aq) is (\*(Aqi\-mingo\-tom\*(Aq) |
| 442 |
\& alternate_language_tags(\*(Aqx\-klikitat\*(Aq) is (\*(Aqi\-klikitat\*(Aq) |
| 443 |
\& alternate_language_tags(\*(Aqi\-klikitat\*(Aq) is (\*(Aqx\-klikitat\*(Aq) |
| 444 |
.Ve |
| 445 |
.Sp |
| 446 |
This function returns empty-list if given anything other than a formally |
| 447 |
valid language tag. |
| 448 |
.IP \(bu 4 |
| 449 |
the function \f(CW@langs\fR = panic_languages(@accept_languages) |
| 450 |
.Sp |
| 451 |
This function takes a list of 0 or more language |
| 452 |
tags that constitute a given user's Accept-Language list, and |
| 453 |
returns a list of tags for \fIother\fR (non-super) |
| 454 |
languages that are probably acceptable to the user, to be |
| 455 |
used \fIif all else fails\fR. |
| 456 |
.Sp |
| 457 |
For example, if a user accepts only 'ca' (Catalan) and |
| 458 |
\&'es' (Spanish), and the documents/interfaces you have |
| 459 |
available are just in German, Italian, and Chinese, then |
| 460 |
the user will most likely want the Italian one (and not |
| 461 |
the Chinese or German one!), instead of getting |
| 462 |
nothing. So \f(CW\*(C`panic_languages(\*(Aqca\*(Aq, \*(Aqes\*(Aq)\*(C'\fR returns |
| 463 |
a list containing 'it' (Italian). |
| 464 |
.Sp |
| 465 |
English ('en') is \fIalways\fR in the return list, but |
| 466 |
whether it's at the very end or not depends |
| 467 |
on the input languages. This function works by consulting |
| 468 |
an internal table that stipulates what common |
| 469 |
languages are "close" to each other. |
| 470 |
.Sp |
| 471 |
A useful construct you might consider using is: |
| 472 |
.Sp |
| 473 |
.Vb 4 |
| 474 |
\& @fallbacks = super_languages(@accept_languages); |
| 475 |
\& push @fallbacks, panic_languages( |
| 476 |
\& @accept_languages, @fallbacks, |
| 477 |
\& ); |
| 478 |
.Ve |
| 479 |
.IP \(bu 4 |
| 480 |
the function implicate_supers( ...languages... ) |
| 481 |
.Sp |
| 482 |
This takes a list of strings (which are presumed to be language-tags; |
| 483 |
strings that aren't, are ignored); and after each one, this function |
| 484 |
inserts super-ordinate forms that don't already appear in the list. |
| 485 |
The original list, plus these insertions, is returned. |
| 486 |
.Sp |
| 487 |
In other words, it takes this: |
| 488 |
.Sp |
| 489 |
.Vb 1 |
| 490 |
\& pt\-br de\-DE en\-US fr pt\-br\-janeiro |
| 491 |
.Ve |
| 492 |
.Sp |
| 493 |
and returns this: |
| 494 |
.Sp |
| 495 |
.Vb 1 |
| 496 |
\& pt\-br pt de\-DE de en\-US en fr pt\-br\-janeiro |
| 497 |
.Ve |
| 498 |
.Sp |
| 499 |
This function is most useful in the idiom |
| 500 |
.Sp |
| 501 |
.Vb 1 |
| 502 |
\& implicate_supers( I18N::LangTags::Detect::detect() ); |
| 503 |
.Ve |
| 504 |
.Sp |
| 505 |
(See I18N::LangTags::Detect.) |
| 506 |
.IP \(bu 4 |
| 507 |
the function implicate_supers_strictly( ...languages... ) |
| 508 |
.Sp |
| 509 |
This works like \f(CW\*(C`implicate_supers\*(C'\fR except that the implicated |
| 510 |
forms are added to the end of the return list. |
| 511 |
.Sp |
| 512 |
In other words, implicate_supers_strictly takes a list of strings |
| 513 |
(which are presumed to be language-tags; strings that aren't, are |
| 514 |
ignored) and after the whole given list, it inserts the super-ordinate forms |
| 515 |
of all given tags, minus any tags that already appear in the input list. |
| 516 |
.Sp |
| 517 |
In other words, it takes this: |
| 518 |
.Sp |
| 519 |
.Vb 1 |
| 520 |
\& pt\-br de\-DE en\-US fr pt\-br\-janeiro |
| 521 |
.Ve |
| 522 |
.Sp |
| 523 |
and returns this: |
| 524 |
.Sp |
| 525 |
.Vb 1 |
| 526 |
\& pt\-br de\-DE en\-US fr pt\-br\-janeiro pt de en |
| 527 |
.Ve |
| 528 |
.Sp |
| 529 |
The reason this function has "_strictly" in its name is that when |
| 530 |
you're processing an Accept-Language list according to the RFCs, if |
| 531 |
you interpret the RFCs quite strictly, then you would use |
| 532 |
implicate_supers_strictly, but for normal use (i.e., common-sense use, |
| 533 |
as far as I'm concerned) you'd use implicate_supers. |
| 534 |
.SH "ABOUT LOWERCASING" |
| 535 |
.IX Header "ABOUT LOWERCASING" |
| 536 |
I've considered making all the above functions that output language |
| 537 |
tags return all those tags strictly in lowercase. Having all your |
| 538 |
language tags in lowercase does make some things easier. But you |
| 539 |
might as well just lowercase as you like, or call |
| 540 |
\&\f(CWencode_language_tag($lang1)\fR where appropriate. |
| 541 |
.SH "ABOUT UNICODE PLAINTEXT LANGUAGE TAGS" |
| 542 |
.IX Header "ABOUT UNICODE PLAINTEXT LANGUAGE TAGS" |
| 543 |
In some future version of I18N::LangTags, I plan to include support |
| 544 |
for RFC2482\-style language tags \-\- which are basically just normal |
| 545 |
language tags with their ASCII characters shifted into Plane 14. |
| 546 |
.SH "SEE ALSO" |
| 547 |
.IX Header "SEE ALSO" |
| 548 |
* I18N::LangTags::List |
| 549 |
.PP |
| 550 |
* RFC 3066, \f(CW\*(C`<http://www.ietf.org/rfc/rfc3066.txt>\*(C'\fR, "Tags for the |
| 551 |
Identification of Languages". (Obsoletes RFC 1766) |
| 552 |
.PP |
| 553 |
* RFC 2277, \f(CW\*(C`<http://www.ietf.org/rfc/rfc2277.txt>\*(C'\fR, "IETF Policy on |
| 554 |
Character Sets and Languages". |
| 555 |
.PP |
| 556 |
* RFC 2231, \f(CW\*(C`<http://www.ietf.org/rfc/rfc2231.txt>\*(C'\fR, "MIME Parameter |
| 557 |
Value and Encoded Word Extensions: Character Sets, Languages, and |
| 558 |
Continuations". |
| 559 |
.PP |
| 560 |
* RFC 2482, \f(CW\*(C`<http://www.ietf.org/rfc/rfc2482.txt>\*(C'\fR, |
| 561 |
"Language Tagging in Unicode Plain Text". |
| 562 |
.PP |
| 563 |
* Locale::Codes, in |
| 564 |
\&\f(CW\*(C`<http://www.perl.com/CPAN/modules/by\-module/Locale/>\*(C'\fR |
| 565 |
.PP |
| 566 |
* ISO 639\-2, "Codes for the representation of names of languages", |
| 567 |
including two-letter and three-letter codes, |
| 568 |
\&\f(CW\*(C`<http://www.loc.gov/standards/iso639\-2/php/code_list.php>\*(C'\fR |
| 569 |
.PP |
| 570 |
* The IANA list of registered languages (hopefully up-to-date), |
| 571 |
\&\f(CW\*(C`<http://www.iana.org/assignments/language\-tags>\*(C'\fR |
| 572 |
.SH COPYRIGHT |
| 573 |
.IX Header "COPYRIGHT" |
| 574 |
Copyright (c) 1998+ Sean M. Burke. All rights reserved. |
| 575 |
.PP |
| 576 |
This library is free software; you can redistribute it and/or |
| 577 |
modify it under the same terms as Perl itself. |
| 578 |
.PP |
| 579 |
The programs and documentation in this dist are distributed in |
| 580 |
the hope that they will be useful, but without any warranty; without |
| 581 |
even the implied warranty of merchantability or fitness for a |
| 582 |
particular purpose. |
| 583 |
.SH AUTHOR |
| 584 |
.IX Header "AUTHOR" |
| 585 |
Sean M. Burke \f(CW\*(C`[email protected]\*(C'\fR |