{
    "mode": "perldoc",
    "parameter": "I18N::LangTags",
    "section": "",
    "url": "https://www.chedong.com/phpMan.php/perldoc/I18N%3A%3ALangTags/json",
    "generated": "2026-05-30T06:12:41Z",
    "synopsis": "use I18N::LangTags();\n...or specify whichever of those functions you want to import, like so:\nuse I18N::LangTags qw(implicatesupers similaritylanguagetag);\nAll the exportable functions are listed below -- you're free to import\nonly some, or none at all. By default, none are imported. If you say:\nuse I18N::LangTags qw(:ALL)\n...then all are exported. (This saves you from having to use something\nless obvious like \"use I18N::LangTags qw(/./)\".)\nIf you don't import any of these functions, assume a &I18N::LangTags::\nin front of all the function names in the following examples.",
    "sections": {
        "NAME": {
            "content": "I18N::LangTags - functions for dealing with RFC3066-style language tags\n",
            "subsections": []
        },
        "SYNOPSIS": {
            "content": "use I18N::LangTags();\n\n...or specify whichever of those functions you want to import, like so:\n\nuse I18N::LangTags qw(implicatesupers similaritylanguagetag);\n\nAll the exportable functions are listed below -- you're free to import\nonly some, or none at all. By default, none are imported. If you say:\n\nuse I18N::LangTags qw(:ALL)\n\n...then all are exported. (This saves you from having to use something\nless obvious like \"use I18N::LangTags qw(/./)\".)\n\nIf you don't import any of these functions, assume a &I18N::LangTags::\nin front of all the function names in the following examples.\n",
            "subsections": []
        },
        "DESCRIPTION": {
            "content": "Language tags are a formalism, described in RFC 3066 (obsoleting 1766),\nfor declaring what language form (language and possibly dialect) a given\nchunk of information is in.\n\nThis library provides functions for common tasks involving language tags\nas they are needed in a variety of protocols and applications.\n\nPlease see the \"See Also\" references for a thorough explanation of how\nto correctly use language tags.\n\n*   the function islanguagetag($lang1)\n\nReturns true iff $lang1 is a formally valid language tag.\n\nislanguagetag(\"fr\")            is TRUE\nislanguagetag(\"x-jicarilla\")   is FALSE\n(Subtags can be 8 chars long at most -- 'jicarilla' is 9)\n\nislanguagetag(\"sgn-US\")    is TRUE\n(That's American Sign Language)\n\nislanguagetag(\"i-Klikitat\")    is TRUE\n(True without regard to the fact noone has actually\nregistered Klikitat -- it's a formally valid tag)\n\nislanguagetag(\"fr-patois\")     is TRUE\n(Formally valid -- altho descriptively weak!)\n\nislanguagetag(\"Spanish\")       is FALSE\nislanguagetag(\"french-patois\") is FALSE\n(No good -- first subtag has to match\n/^([xXiI]|[a-zA-Z]{2,3})$/ -- see RFC3066)\n\nislanguagetag(\"x-borg-prot2532\") is TRUE\n(Yes, subtags can contain digits, as of RFC3066)\n\n*   the function extractlanguagetags($whatever)\n\nReturns a list of whatever looks like formally valid language tags\nin $whatever. Not very smart, so don't get too creative with what\nyou want to feed it.\n\nextractlanguagetags(\"fr, fr-ca, i-mingo\")\nreturns:   ('fr', 'fr-ca', 'i-mingo')\n\nextractlanguagetags(\"It's like this: I'm in fr -- French!\")\nreturns:   ('It', 'in', 'fr')\n(So don't just feed it any old thing.)\n\nThe output is untainted. If you don't know what tainting is, don't\nworry about it.\n\n*   the function samelanguagetag($lang1, $lang2)\n\nReturns true iff $lang1 and $lang2 are acceptable variant tags\nrepresenting the same language-form.\n\nsamelanguagetag('x-kadara', 'i-kadara')  is TRUE\n(The x/i- alternation doesn't matter)\nsamelanguagetag('X-KADARA', 'i-kadara')  is TRUE\n(...and neither does case)\nsamelanguagetag('en',       'en-US')     is FALSE\n(all-English is not the SAME as US English)\nsamelanguagetag('x-kadara', 'x-kadar')   is FALSE\n(these are totally unrelated tags)\nsamelanguagetag('no-bok',    'nb')       is TRUE\n(no-bok is a legacy tag for nb (Norwegian Bokmal))\n\n\"samelanguagetag\" works by just seeing whether\n\"encodelanguagetag($lang1)\" is the same as\n\"encodelanguagetag($lang2)\".\n\n(Yes, I know this function is named a bit oddly. Call it historic\nreasons.)\n\n*   the function similaritylanguagetag($lang1, $lang2)\n\nReturns an integer representing the degree of similarity between\ntags $lang1 and $lang2 (the order of which does not matter), where\nsimilarity is the number of common elements on the left, without\nregard to case and to x/i- alternation.\n\nsimilaritylanguagetag('fr', 'fr-ca')           is 1\n(one element in common)\nsimilaritylanguagetag('fr-ca', 'fr-FR')        is 1\n(one element in common)\n\nsimilaritylanguagetag('fr-CA-joual',\n'fr-CA-PEI')             is 2\nsimilaritylanguagetag('fr-CA-joual', 'fr-CA')  is 2\n(two elements in common)\n\nsimilaritylanguagetag('x-kadara', 'i-kadara')  is 1\n(x/i- doesn't matter)\n\nsimilaritylanguagetag('en',       'x-kadar')   is 0\nsimilaritylanguagetag('x-kadara', 'x-kadar')   is 0\n(unrelated tags -- no similarity)\n\nsimilaritylanguagetag('i-cree-syllabic',\n'i-cherokee-syllabic')   is 0\n(no B<leftmost> elements in common!)\n\n*   the function isdialectof($lang1, $lang2)\n\nReturns true iff language tag $lang1 represents a subform of\nlanguage tag $lang2.\n\nGet the order right! It doesn't work the other way around!\n\nisdialectof('en-US', 'en')            is TRUE\n(American English IS a dialect of all-English)\n\nisdialectof('fr-CA-joual', 'fr-CA')   is TRUE\nisdialectof('fr-CA-joual', 'fr')      is TRUE\n(Joual is a dialect of (a dialect of) French)\n\nisdialectof('en', 'en-US')            is FALSE\n(all-English is a NOT dialect of American English)\n\nisdialectof('fr', 'en-CA')            is FALSE\n\nisdialectof('en',    'en'   )         is TRUE\nisdialectof('en-US', 'en-US')         is TRUE\n(B<Note:> these are degenerate cases)\n\nisdialectof('i-mingo-tom', 'x-Mingo') is TRUE\n(the x/i thing doesn't matter, nor does case)\n\nisdialectof('nn', 'no')               is TRUE\n(because 'nn' (New Norse) is aliased to 'no-nyn',\nas a special legacy case, and 'no-nyn' is a\nsubform of 'no' (Norwegian))\n\n*   the function superlanguages($lang1)\n\nReturns a list of language tags that are superordinate tags to\n$lang1 -- it gets this by removing subtags from the end of $lang1\nuntil nothing (or just \"i\" or \"x\") is left.\n\nsuperlanguages(\"fr-CA-joual\")  is  (\"fr-CA\", \"fr\")\n\nsuperlanguages(\"en-AU\")  is  (\"en\")\n\nsuperlanguages(\"en\")  is  empty-list, ()\n\nsuperlanguages(\"i-cherokee\")  is  empty-list, ()\n...not (\"i\"), which would be illegal as well as pointless.\n\nIf $lang1 is not a valid language tag, returns empty-list in a list\ncontext, undef in a scalar context.\n\nA notable and rather unavoidable problem with this method:\n\"x-mingo-tom\" has an \"x\" because the whole tag isn't an\nIANA-registered tag -- but superlanguages('x-mingo-tom') is\n('x-mingo') -- which isn't really right, since 'i-mingo' is\nregistered. But this module has no way of knowing that. (But note\nthat samelanguagetag('x-mingo', 'i-mingo') is TRUE.)\n\nMore importantly, you assume *at your peril* that superordinates of\n$lang1 are mutually intelligible with $lang1. Consider this\ncarefully.\n\n*   the function locale2languagetag($localeidentifier)\n\nThis takes a locale name (like \"en\", \"enUS\", or \"enUS.ISO8859-1\")\nand maps it to a language tag. If it's not mappable (as with,\nnotably, \"C\" and \"POSIX\"), this returns empty-list in a list\ncontext, or undef in a scalar context.\n\nlocale2languagetag(\"en\") is \"en\"\n\nlocale2languagetag(\"enUS\") is \"en-US\"\n\nlocale2languagetag(\"enUS.ISO8859-1\") is \"en-US\"\n\nlocale2languagetag(\"C\") is undef or ()\n\nlocale2languagetag(\"POSIX\") is undef or ()\n\nlocale2languagetag(\"POSIX\") is undef or ()\n\nI'm not totally sure that locale names map satisfactorily to\nlanguage tags. Think REAL hard about how you use this. YOU HAVE BEEN\nWARNED.\n\nThe output is untainted. If you don't know what tainting is, don't\nworry about it.\n\n*   the function encodelanguagetag($lang1)\n\nThis function, if given a language tag, returns an encoding of it\nsuch that:\n\n* tags representing different languages never get the same encoding.\n\n* tags representing the same language always get the same encoding.\n\n* an encoding of a formally valid language tag always is a string\nvalue that is defined, has length, and is true if considered as a\nboolean.\n\nNote that the encoding itself is not a formally valid language tag.\nNote also that you cannot, currently, go from an encoding back to a\nlanguage tag that it's an encoding of.\n\nNote also that you must consider the encoded value as atomic; i.e.,\nyou should not consider it as anything but an opaque, unanalysable\nstring value. (The internals of the encoding method may change in\nfuture versions, as the language tagging standard changes over\ntime.)\n\n\"encodelanguagetag\" returns undef if given anything other than a\nformally valid language tag.\n\nThe reason \"encodelanguagetag\" exists is because different\nlanguage tags may represent the same language; this is normally\ntreatable with \"samelanguagetag\", but consider this situation:\n\nYou have a data file that expresses greetings in different\nlanguages. Its format is \"[language tag]=[how to say 'Hello']\",\nlike:\n\nen-US=Hiho\nfr=Bonjour\ni-mingo=Hau'\n\nAnd suppose you write a program that reads that file and then runs\nas a daemon, answering client requests that specify a language tag\nand then expect the string that says how to greet in that language.\nSo an interaction looks like:\n\ngreeting-client asks:    fr\ngreeting-server answers: Bonjour\n\nSo far so good. But suppose the way you're implementing this is:\n\nmy %greetings;\ndie unless open(IN, \"<\", \"in.dat\");\nwhile(<IN>) {\nchomp;\nnext unless /^([^=]+)=(.+)/s;\nmy($lang, $expr) = ($1, $2);\n$greetings{$lang} = $expr;\n}\nclose(IN);\n\nat which point %greetings has the contents:\n\n\"en-US\"   => \"Hiho\"\n\"fr\"      => \"Bonjour\"\n\"i-mingo\" => \"Hau'\"\n\nAnd suppose then that you answer client requests for language\n$wanted by just looking up $greetings{$wanted}.\n\nIf the client asks for \"fr\", that will look up successfully in\n%greetings, to the value \"Bonjour\". And if the client asks for\n\"i-mingo\", that will look up successfully in %greetings, to the\nvalue \"Hau'\".\n\nBut if the client asks for \"i-Mingo\" or \"x-mingo\", or \"Fr\", then the\nlookup in %greetings fails. That's the Wrong Thing.\n\nYou could instead do lookups on $wanted with:\n\nuse I18N::LangTags qw(samelanguagetag);\nmy $response = '';\nforeach my $l2 (keys %greetings) {\nif(samelanguagetag($wanted, $l2)) {\n$response = $greetings{$l2};\nlast;\n}\n}\n\nBut that's rather inefficient. A better way to do it is to start\nyour program with:\n\nuse I18N::LangTags qw(encodelanguagetag);\nmy %greetings;\ndie unless open(IN, \"<\", \"in.dat\");\nwhile(<IN>) {\nchomp;\nnext unless /^([^=]+)=(.+)/s;\nmy($lang, $expr) = ($1, $2);\n$greetings{\nencodelanguagetag($lang)\n} = $expr;\n}\nclose(IN);\n\nand then just answer client requests for language $wanted by just\nlooking up\n\n$greetings{encodelanguagetag($wanted)}\n\nAnd that does the Right Thing.\n\n*   the function alternatelanguagetags($lang1)\n\nThis function, if given a language tag, returns all language tags\nthat are alternate forms of this language tag. (I.e., tags which\nrefer to the same language.) This is meant to handle legacy tags\ncaused by the minor changes in language tag standards over the\nyears; and the x-/i- alternation is also dealt with.\n\nNote that this function does *not* try to equate new (and\nnever-used, and unusable) ISO639-2 three-letter tags to old (and\nstill in use) ISO639-1 two-letter equivalents -- like \"ara\" -> \"ar\"\n-- because \"ara\" has *never* been in use as an Internet language\ntag, and RFC 3066 stipulates that it never should be, since a\nshorter tag (\"ar\") exists.\n\nExamples:\n\nalternatelanguagetags('no-bok')       is ('nb')\nalternatelanguagetags('nb')           is ('no-bok')\nalternatelanguagetags('he')           is ('iw')\nalternatelanguagetags('iw')           is ('he')\nalternatelanguagetags('i-hakka')      is ('zh-hakka', 'x-hakka')\nalternatelanguagetags('zh-hakka')     is ('i-hakka', 'x-hakka')\nalternatelanguagetags('en')           is ()\nalternatelanguagetags('x-mingo-tom')  is ('i-mingo-tom')\nalternatelanguagetags('x-klikitat')   is ('i-klikitat')\nalternatelanguagetags('i-klikitat')   is ('x-klikitat')\n\nThis function returns empty-list if given anything other than a\nformally valid language tag.\n\n*   the function @langs = paniclanguages(@acceptlanguages)\n\nThis function takes a list of 0 or more language tags that\nconstitute a given user's Accept-Language list, and returns a list\nof tags for *other* (non-super) languages that are probably\nacceptable to the user, to be used *if all else fails*.\n\nFor example, if a user accepts only 'ca' (Catalan) and 'es'\n(Spanish), and the documents/interfaces you have available are just\nin German, Italian, and Chinese, then the user will most likely want\nthe Italian one (and not the Chinese or German one!), instead of\ngetting nothing. So \"paniclanguages('ca', 'es')\" returns a list\ncontaining 'it' (Italian).\n\nEnglish ('en') is *always* in the return list, but whether it's at\nthe very end or not depends on the input languages. This function\nworks by consulting an internal table that stipulates what common\nlanguages are \"close\" to each other.\n\nA useful construct you might consider using is:\n\n@fallbacks = superlanguages(@acceptlanguages);\npush @fallbacks, paniclanguages(\n@acceptlanguages, @fallbacks,\n);\n\n*   the function implicatesupers( ...languages... )\n\nThis takes a list of strings (which are presumed to be\nlanguage-tags; strings that aren't, are ignored); and after each\none, this function inserts super-ordinate forms that don't already\nappear in the list. The original list, plus these insertions, is\nreturned.\n\nIn other words, it takes this:\n\npt-br de-DE en-US fr pt-br-janeiro\n\nand returns this:\n\npt-br pt de-DE de en-US en fr pt-br-janeiro\n\nThis function is most useful in the idiom\n\nimplicatesupers( I18N::LangTags::Detect::detect() );\n\n(See I18N::LangTags::Detect.)\n\n*   the function implicatesupersstrictly( ...languages... )\n\nThis works like \"implicatesupers\" except that the implicated forms\nare added to the end of the return list.\n\nIn other words, implicatesupersstrictly takes a list of strings\n(which are presumed to be language-tags; strings that aren't, are\nignored) and after the whole given list, it inserts the\nsuper-ordinate forms of all given tags, minus any tags that already\nappear in the input list.\n\nIn other words, it takes this:\n\npt-br de-DE en-US fr pt-br-janeiro\n\nand returns this:\n\npt-br de-DE en-US fr pt-br-janeiro pt de en\n\nThe reason this function has \"strictly\" in its name is that when\nyou're processing an Accept-Language list according to the RFCs, if\nyou interpret the RFCs quite strictly, then you would use\nimplicatesupersstrictly, but for normal use (i.e., common-sense\nuse, as far as I'm concerned) you'd use implicatesupers.\n",
            "subsections": []
        },
        "ABOUT LOWERCASING": {
            "content": "I've considered making all the above functions that output language tags\nreturn all those tags strictly in lowercase. Having all your language\ntags in lowercase does make some things easier. But you might as well\njust lowercase as you like, or call \"encodelanguagetag($lang1)\" where\nappropriate.\n",
            "subsections": []
        },
        "ABOUT UNICODE PLAINTEXT LANGUAGE TAGS": {
            "content": "In some future version of I18N::LangTags, I plan to include support for\nRFC2482-style language tags -- which are basically just normal language\ntags with their ASCII characters shifted into Plane 14.\n",
            "subsections": []
        },
        "SEE ALSO": {
            "content": "* I18N::LangTags::List\n\n* RFC 3066, \"<http://www.ietf.org/rfc/rfc3066.txt>\", \"Tags for the\nIdentification of Languages\". (Obsoletes RFC 1766)\n\n* RFC 2277, \"<http://www.ietf.org/rfc/rfc2277.txt>\", \"IETF Policy on\nCharacter Sets and Languages\".\n\n* RFC 2231, \"<http://www.ietf.org/rfc/rfc2231.txt>\", \"MIME Parameter\nValue and Encoded Word Extensions: Character Sets, Languages, and\nContinuations\".\n\n* RFC 2482, \"<http://www.ietf.org/rfc/rfc2482.txt>\", \"Language Tagging\nin Unicode Plain Text\".\n\n* Locale::Codes, in\n\"<http://www.perl.com/CPAN/modules/by-module/Locale/>\"\n\n* ISO 639-2, \"Codes for the representation of names of languages\",\nincluding two-letter and three-letter codes,\n\"<http://www.loc.gov/standards/iso639-2/php/codelist.php>\"\n\n* The IANA list of registered languages (hopefully up-to-date),\n\"<http://www.iana.org/assignments/language-tags>\"\n",
            "subsections": []
        },
        "COPYRIGHT": {
            "content": "Copyright (c) 1998+ Sean M. Burke. All rights reserved.\n\nThis library is free software; you can redistribute it and/or modify it\nunder the same terms as Perl itself.\n\nThe programs and documentation in this dist are distributed in the hope\nthat they will be useful, but without any warranty; without even the\nimplied warranty of merchantability or fitness for a particular purpose.\n",
            "subsections": []
        },
        "AUTHOR": {
            "content": "Sean M. Burke \"sburke@cpan.org\"\n",
            "subsections": []
        }
    },
    "summary": "I18N::LangTags - functions for dealing with RFC3066-style language tags",
    "flags": [],
    "examples": [],
    "see_also": []
}