Locale.ForLanguageTag(String) Method
Definition
Important
Some information relates to prerelease product that may be substantially modified before it’s released. Microsoft makes no warranties, express or implied, with respect to the information provided here.
Returns a locale for the specified IETF BCP 47 language tag string.
[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
- languageTag
- String
the language tag
Returns
The locale that best represents the language tag.
- Attributes
Exceptions
if languageTag
is null
.
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.