ResourceBundle.Control.GetCandidateLocales(String, Locale) Method

Reference

Definition

Namespace:: Java.Util

Assembly:: Mono.Android.dll

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 List of Locales as candidate locales for baseName and locale.

[Android.Runtime.Register("getCandidateLocales", "(Ljava/lang/String;Ljava/util/Locale;)Ljava/util/List;", "GetGetCandidateLocales_Ljava_lang_String_Ljava_util_Locale_Handler")]
public virtual System.Collections.Generic.IList<Java.Util.Locale>? GetCandidateLocales (string baseName, Java.Util.Locale locale);

[<Android.Runtime.Register("getCandidateLocales", "(Ljava/lang/String;Ljava/util/Locale;)Ljava/util/List;", "GetGetCandidateLocales_Ljava_lang_String_Ljava_util_Locale_Handler")>]
abstract member GetCandidateLocales : string * Java.Util.Locale -> System.Collections.Generic.IList<Java.Util.Locale>
override this.GetCandidateLocales : string * Java.Util.Locale -> System.Collections.Generic.IList<Java.Util.Locale>

Parameters

baseName: String

the base name of the resource bundle, a fully qualified class name

locale: Locale

the locale for which a resource bundle is desired

Returns

IList<Locale>

a List of candidate Locales for the given locale

Attributes: RegisterAttribute

Remarks

Returns a List of Locales as candidate locales for baseName and locale. This method is called by the ResourceBundle.getBundle factory method each time the factory method tries finding a resource bundle for a target Locale.

The sequence of the candidate locales also corresponds to the runtime resource lookup path (also known as the parent chain), if the corresponding resource bundles for the candidate locales exist and their parents are not defined by loaded resource bundles themselves. The last element of the list must be a Locale#ROOT root locale if it is desired to have the base bundle as the terminal of the parent chain.

If the given locale is equal to Locale.ROOT (the root locale), a List containing only the root Locale must be returned. In this case, the ResourceBundle.getBundle factory method loads only the base bundle as the resulting resource bundle.

It is not a requirement to return an immutable (unmodifiable) List. However, the returned List must not be mutated after it has been returned by getCandidateLocales.

The default implementation returns a List containing Locales using the rules described below. In the description below, L, S, C and V respectively represent non-empty language, script, country, and variant. For example, [L, C] represents a Locale that has non-empty values only for language and country. The form L("xx") represents the (non-empty) language value is "xx". For all cases, Locales whose final component values are empty strings are omitted.

<ol><li>For an input Locale with an empty script value, append candidate Locales by omitting the final component one by one as below:

<ul> <li> [L, C, V] </li> <li> [L, C] </li> <li> [L] </li> <li> Locale.ROOT</li> </ul></li>

<li>For an input Locale with a non-empty script value, append candidate Locales by omitting the final component up to language, then append candidates generated from the Locale with country and variant restored:

<ul> <li> [L, S, C, V]</li> <li> [L, S, C]</li> <li> [L, S]</li> <li> [L, C, V]</li> <li> [L, C]</li> <li> [L]</li> <li> Locale.ROOT</li> </ul></li>

<li>For an input Locale with a variant value consisting of multiple subtags separated by underscore, generate candidate Locales by omitting the variant subtags one by one, then insert them after every occurrence of Locales with the full variant value in the original list. For example, if the variant consists of two subtags V1 and V2:

<ul> <li> [L, S, C, V1, V2]</li> <li> [L, S, C, V1]</li> <li> [L, S, C]</li> <li> [L, S]</li> <li> [L, C, V1, V2]</li> <li> [L, C, V1]</li> <li> [L, C]</li> <li> [L]</li> <li> Locale.ROOT</li> </ul></li>

<li>Special cases for Chinese. When an input Locale has the language "zh" (Chinese) and an empty script value, either "Hans" (Simplified) or "Hant" (Traditional) might be supplied, depending on the country. When the country is "CN" (China) or "SG" (Singapore), "Hans" is supplied. When the country is "HK" (Hong Kong SAR China), "MO" (Macau SAR China), or "TW" (Taiwan), "Hant" is supplied. For all other countries or when the country is empty, no script is supplied. For example, for Locale("zh", "CN") , the candidate list will be: <ul> <li> [L("zh"), S("Hans"), C("CN")]</li> <li> [L("zh"), S("Hans")]</li> <li> [L("zh"), C("CN")]</li> <li> [L("zh")]</li> <li> Locale.ROOT</li> </ul>

For Locale("zh", "TW"), the candidate list will be: <ul> <li> [L("zh"), S("Hant"), C("TW")]</li> <li> [L("zh"), S("Hant")]</li> <li> [L("zh"), C("TW")]</li> <li> [L("zh")]</li> <li> Locale.ROOT</li> </ul></li>

<li>Special cases for Norwegian. Both Locale("no", "NO", "NY") and Locale("nn", "NO") represent Norwegian Nynorsk. When a locale's language is "nn", the standard candidate list is generated up to [L("nn")], and then the following candidates are added:

<ul><li> [L("no"), C("NO"), V("NY")]</li> <li> [L("no"), C("NO")]</li> <li> [L("no")]</li> <li> Locale.ROOT</li> </ul>

If the locale is exactly Locale("no", "NO", "NY"), it is first converted to Locale("nn", "NO") and then the above procedure is followed.

Also, Java treats the language "no" as a synonym of Norwegian Bokmål "nb". Except for the single case Locale("no", "NO", "NY") (handled above), when an input Locale has language "no" or "nb", candidate Locales with language code "no" and "nb" are interleaved, first using the requested language, then using its synonym. For example, Locale("nb", "NO", "POSIX") generates the following candidate list:

<ul> <li> [L("nb"), C("NO"), V("POSIX")]</li> <li> [L("no"), C("NO"), V("POSIX")]</li> <li> [L("nb"), C("NO")]</li> <li> [L("no"), C("NO")]</li> <li> [L("nb")]</li> <li> [L("no")]</li> <li> Locale.ROOT</li> </ul>

Locale("no", "NO", "POSIX") would generate the same list except that locales with "no" would appear before the corresponding locales with "nb".</li> </ol>

The default implementation uses an ArrayList that overriding implementations may modify before returning it to the caller. However, a subclass must not modify it after it has been returned by getCandidateLocales.

For example, if the given baseName is "Messages" and the given locale is Locale("ja", "", "XX"), then a List of Locales:

Locale("ja", "", "XX")
                Locale("ja")
                Locale.ROOT

is returned. And if the resource bundles for the "ja" and "" Locales are found, then the runtime resource lookup path (parent chain) is:

{@code
                Messages_ja -> Messages
            }

Java documentation for java.util.ResourceBundle.Control.getCandidateLocales(java.lang.String, java.util.Locale).

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

Share via