Locale.ForLanguageTag(String) Method

[Android.Runtime.Register("forLanguageTag", "(Ljava/lang/String;)Ljava/util/Locale;", "")]
public static Java.Util.Locale ForLanguageTag (string languageTag);

[<Android.Runtime.Register("forLanguageTag", "(Ljava/lang/String;)Ljava/util/Locale;", "")>]
static member ForLanguageTag : string -> Java.Util.Locale

Parameters

Returns

The locale that best represents the language tag.

Attributes

RegisterAttribute

Exceptions

Remarks

Returns a locale for the specified IETF BCP 47 language tag string.

If the specified language tag contains any ill-formed subtags, the first such subtag and all following subtags are ignored. Compare to Locale.Builder#setLanguageTag which throws an exception in this case.

The following <b>conversions</b> are performed:<ul>

<li>The language code "und" is mapped to language "".

<li>The language codes "he", "yi", and "id" are mapped to "iw", "ji", and "in" respectively. (This is the same canonicalization that's done in Locale's constructors.)

<li>The portion of a private use subtag prefixed by "lvariant", if any, is removed and appended to the variant field in the result locale (without case normalization). If it is then empty, the private use subtag is discarded:

Locale loc;
                loc = Locale.forLanguageTag("en-US-x-lvariant-POSIX");
                loc.getVariant(); // returns "POSIX"
                loc.getExtension('x'); // returns null

                loc = Locale.forLanguageTag("de-POSIX-x-URP-lvariant-Abc-Def");
                loc.getVariant(); // returns "POSIX_Abc_Def"
                loc.getExtension('x'); // returns "urp"

<li>When the languageTag argument contains an extlang subtag, the first such subtag is used as the language, and the primary language subtag and other extlang subtags are ignored:

Locale.forLanguageTag("ar-aao").getLanguage(); // returns "aao"
                Locale.forLanguageTag("en-abc-def-us").toString(); // returns "abc_US"

<li>Case is normalized except for variant tags, which are left unchanged. Language is normalized to lower case, script to title case, country to upper case, and extensions to lower case.

<li>If, after processing, the locale would exactly match either ja_JP_JP or th_TH_TH with no extensions, the appropriate extensions are added as though the constructor had been called:

Locale.forLanguageTag("ja-JP-x-lvariant-JP").toLanguageTag();
               // returns "ja-JP-u-ca-japanese-x-lvariant-JP"
               Locale.forLanguageTag("th-TH-x-lvariant-TH").toLanguageTag();
               // returns "th-TH-u-nu-thai-x-lvariant-TH"

</ul>

This implements the 'Language-Tag' production of BCP47, and so supports grandfathered (regular and irregular) as well as private use language tags. Stand alone private use tags are represented as empty language and extension 'x-whatever', and grandfathered tags are converted to their canonical replacements where they exist.

Grandfathered tags with canonical replacements are as follows:

<table class="striped"> <caption style="display:none">Grandfathered tags with canonical replacements</caption> <thead style="text-align:center"> <tr><th scope="col" style="padding: 0 2px">grandfathered tag</th><th scope="col" style="padding: 0 2px">modern replacement</th></tr> </thead> <tbody style="text-align:center"> <tr><th scope="row">art-lojban</th><td>jbo</td></tr> <tr><th scope="row">i-ami</th><td>ami</td></tr> <tr><th scope="row">i-bnn</th><td>bnn</td></tr> <tr><th scope="row">i-hak</th><td>hak</td></tr> <tr><th scope="row">i-klingon</th><td>tlh</td></tr> <tr><th scope="row">i-lux</th><td>lb</td></tr> <tr><th scope="row">i-navajo</th><td>nv</td></tr> <tr><th scope="row">i-pwn</th><td>pwn</td></tr> <tr><th scope="row">i-tao</th><td>tao</td></tr> <tr><th scope="row">i-tay</th><td>tay</td></tr> <tr><th scope="row">i-tsu</th><td>tsu</td></tr> <tr><th scope="row">no-bok</th><td>nb</td></tr> <tr><th scope="row">no-nyn</th><td>nn</td></tr> <tr><th scope="row">sgn-BE-FR</th><td>sfb</td></tr> <tr><th scope="row">sgn-BE-NL</th><td>vgt</td></tr> <tr><th scope="row">sgn-CH-DE</th><td>sgg</td></tr> <tr><th scope="row">zh-guoyu</th><td>cmn</td></tr> <tr><th scope="row">zh-hakka</th><td>hak</td></tr> <tr><th scope="row">zh-min-nan</th><td>nan</td></tr> <tr><th scope="row">zh-xiang</th><td>hsn</td></tr> </tbody> </table>

Grandfathered tags with no modern replacement will be converted as follows:

<table class="striped"> <caption style="display:none">Grandfathered tags with no modern replacement</caption> <thead style="text-align:center"> <tr><th scope="col" style="padding: 0 2px">grandfathered tag</th><th scope="col" style="padding: 0 2px">converts to</th></tr> </thead> <tbody style="text-align:center"> <tr><th scope="row">cel-gaulish</th><td>xtg-x-cel-gaulish</td></tr> <tr><th scope="row">en-GB-oed</th><td>en-GB-x-oed</td></tr> <tr><th scope="row">i-default</th><td>en-x-i-default</td></tr> <tr><th scope="row">i-enochian</th><td>und-x-i-enochian</td></tr> <tr><th scope="row">i-mingo</th><td>see-x-i-mingo</td></tr> <tr><th scope="row">zh-min</th><td>nan-x-zh-min</td></tr> </tbody> </table>

For a list of all grandfathered tags, see the IANA Language Subtag Registry (search for "Type: grandfathered").

<b>Note</b>: there is no guarantee that toLanguageTag and forLanguageTag will round-trip.

Added in 1.7.

Java documentation for java.util.Locale.forLanguageTag(java.lang.String).

Portions of this page are modifications based on work created and shared by the Android Open Source Project and used according to terms described in the Creative Commons 2.5 Attribution License.

Applies to