The Java Tutorials have been written for JDK 8. Examples and practices described in this page don't take advantage of improvements introduced in later releases and might use technology no longer available.
SeeDev.java for updated tutorials taking advantage of the latest releases.
SeeJava Language Changes for a summary of updated language features in Java SE 9 and subsequent releases.
SeeJDK Release Notes for information about new features, enhancements, and removed or deprecated options for all JDK releases.

Language Tag Filtering and Lookup

The Java Programming language contains internationalization support for language tags, language tag filtering, and language tag lookup. These features are specified byIETF BCP 47, which containsRFC 5646 "Tags for Identifying Languages"andRFC 4647 "Matching of Language Tags."This lesson describes how this support is provided in the JDK.

What Are Language Tags?

Language tags are specially formatted strings that provide information about a particular language. A language tag might be something simple (such as "en" for English), something complex (such as "zh-cmn-Hans-CN" for Chinese, Mandarin, Simplified script, as used in China), or something in between (such as "sr-Latn", for Serbian written using Latin script). Language tags consist of "subtags" separated by hyphens; this terminology is used throughout the API documentation.

Thejava.util.Locale class provides support for language tags. ALocale contains several different fields: language (such as "en" for English, or "ja" for Japanese), script (such as "Latn" for Latin or "Cyrl" for Cyrillic), country (such as "US" for United States or "FR" for France), variant (which indicates some variant of a locale), and extensions (which provides a map of single character keys toString values, indicating extensions apart from language identification).To create aLocale object from a language tagString, invokeLocale.forLanguageTag(String), passing in the language tag as its only argument. Doing so creates and returns a newLocale object for use in your application.

Example 1:

package languagetagdemo;import java.util.Locale;public class LanguageTagDemo {     public static void main(String[] args) {         Locale l = Locale.forLanguageTag("en-US");     }}

Note that the Locale API only requires that your language tag be syntactically well-formed. It does not perform any extra validation (such as checking to see if the tag is registered in the IANA Language Subtag Registry).

What Are Language Ranges?

Language ranges (represented by classjava.util.Locale.LanguageRange) identify sets of language tags that share specific attributes. Language ranges are classified as either basic or extended, and are similar to language tags in that they consist of subtags separated by hyphens. Examples of basic language ranges include "en" (English), "ja-JP" (Japanese, Japan), and "*" (a special language range which matches any language tag). Examples of extended language ranges include "*-CH" (any language, Switzerland), "es-*" (Spanish, any regions), and "zh-Hant-*" (Traditional Chinese, any region).

Furthermore, language ranges may be stored in Language Priority Lists, which enable users to prioritize their language preferences in a weighted list. Language Priority Lists are expressed by placingLanguageRange objects into ajava.util.List, which can then be passed to theLocale methods that accept aList ofLanguageRange objects.

Creating a Language Range

TheLocale.LanguageRange class provides two different constructors for creating language ranges:

• public Locale.LanguageRange(String range)
• public Locale.LanguageRange(String range, double weight)

The only difference between them is that the second version allows a weight to be specified; this weight will be considered if the range is placed into a Language Priority List.

Locale.LanguageRange also specifies some constants to be used with these constructors:

• public static final double MAX_WEIGHT
• public static final double MIN_WEIGHT

TheMAX_WEIGHT constant holds a value of 1.0, which indicates that it is a good fit for the user. TheMIN_WEIGHT constant holds a value of 0.0, indicating that it is not.

Example 2:

package languagetagdemo;import java.util.Locale;public class LanguageTagDemo {     public static void main(String[] args) {         // Create Locale         Locale l = Locale.forLanguageTag("en-US");         // Define Some LanguageRange Objects         Locale.LanguageRange range1 = new Locale.LanguageRange("en-US",Locale.LanguageRange.MAX_WEIGHT);         Locale.LanguageRange range2 = new Locale.LanguageRange("en-GB*",0.5);         Locale.LanguageRange range3 = new Locale.LanguageRange("fr-FR",Locale.LanguageRange.MIN_WEIGHT);     }}

Example 2 creates three language ranges: English (United States), English (Great Britain), and French (France). These ranges are weighted to express the user's preferences, in order from most preferred to least preferred.

Creating a Language Priority List

You can create a Language Priority List from a list of language rangesby using theLanguageRange.parse(String) method. This method accepts alist of comma-separated language ranges, performs a syntactic check foreach language range in the given ranges, and then returns the newlycreated Language Priority List.

For detailed information about the required format of the "ranges"parameter, see the API specification for this method.

Example 3:

package languagetagdemo;import java.util.Locale;import java.util.List;public class LanguageTagDemo {    public static void main(String[] args) {        // Create Locale        Locale l = Locale.forLanguageTag("en-US");        // Create a Language Priority List        String ranges = "en-US;q=1.0,en-GB;q=0.5,fr-FR;q=0.0";        List<Locale.LanguageRange> languageRanges = Locale.LanguageRange.parse(ranges)    }}

Example 3 creates the same three language ranges as Example 2, butstores them in aString object, which is passed to theparse(String)method. The returnedList ofLanguageRange objects is the LanguagePriority List.

Filtering Language Tags

Language tag filtering is the process of matching a set of language tags against a user's Language Priority List. The result of filtering will be a complete list of all matching results. TheLocale class defines two filter methods that return a list ofLocale objects. Their signatures are as follows:

• public static List<Locale> filter (List<Locale.LanguageRange> priorityList, Collection<Locale> locales)
• public static List<Locale> filter (List<Locale.LanguageRange> priorityList, Collection<Locale> locales, Locale.FilteringMode mode)

In both methods, the first argument specifies the user's Language Priority List as described in the previous section.

The second argument specifies aCollection ofLocale objects to match against. The match itself will take place according to the rules specified by RFC 4647.

The third argument (if provided) specifies the "filtering mode" to use. TheLocale.FilteringMode enum provides a number of different values to choose from, such asAUTOSELECT_FILTERING (for basic language range filtering) orEXTENDED_FILTERING (for extended language range filtering).

Example 4 provides a demonstration of language tag filtering.

Example 4:

package languagetagdemo;import java.util.Locale;import java.util.Collection;import java.util.List;import java.util.ArrayList;public class LanguageTagDemo {    public static void main(String[] args) {        // Create a collection of Locale objects to filter        Collection<Locale> locales = new ArrayList<>();        locales.add(Locale.forLanguageTag("en-GB"));        locales.add(Locale.forLanguageTag("ja"));        locales.add(Locale.forLanguageTag("zh-cmn-Hans-CN"));        locales.add(Locale.forLanguageTag("en-US"));        // Express the user's preferences with a Language Priority List        String ranges = "en-US;q=1.0,en-GB;q=0.5,fr-FR;q=0.0";        List<Locale.LanguageRange> languageRanges = Locale.LanguageRange.parse(ranges);        // Now filter the Locale objects, returning any matches        List<Locale> results = Locale.filter(languageRanges,locales);        // Print out the matches        for(Locale l : results){        System.out.println(l.toString());        }    }}

The output of this program is:

en_US
en_GB

This returned list is ordered according to the weights specified in the user's Language Priority List.

TheLocale class also definesfilterTags methods for filtering language tags asString objects.

The method signatures are as follows:

• public static List<String> filterTags (List<Locale.LanguageRange> priorityList, Collection<String> tags)
• public static List<String> filterTags (List<Locale.LanguageRange> priorityList, Collection<String> tags, Locale.FilteringMode mode)

Example 5 provides the same search as Example 4, but usesString objects instead ofLocale objects.

Example 5:

package languagetagdemo;import java.util.Locale;import java.util.Collection;import java.util.List;import java.util.ArrayList;public class LanguageTagDemo {    public static void main(String[] args) {        // Create a collection of String objects to match against        Collection<String> tags = new ArrayList<>();        tags.add("en-GB");        tags.add("ja");        tags.add("zh-cmn-Hans-CN");        tags.add("en-US");        // Express user's preferences with a Language Priority List        String ranges = "en-US;q=1.0,en-GB;q=0.5,fr-FR;q=0.0";        List<Locale.LanguageRange> languageRanges = Locale.LanguageRange.parse(ranges);        // Now search the locales for the best match        List<String> results = Locale.filterTags(languageRanges,tags);        // Print out the matches        for(String s : results){            System.out.println(s);        }    }}

As before, the search will match and return "en-US" and "en-GB" (in that order).

Performing Language Tag Lookup

In contrast to language tag filtering, language tag lookup is the process of matching language ranges to sets of language tags and returning the one language tag that best matches the range. RFC4647 states that: "Lookup produces the single result that best matches the user's preferences from the list of available tags, so it is useful in cases in which a single item is required (and for which only a single item can be returned). For example, if a process were to insert a human-readable error message into a protocol header, it might select the text based on the user's language priority list. Since the process can return only one item, it is forced to choose a single item and it has to return some item, even if none of the content's language tags match the language priority list supplied by the user."

Example 6:

package languagetagdemo;import java.util.Locale;import java.util.Collection;import java.util.List;import java.util.ArrayList;public class LanguageTagDemo {    public static void main(String[] args) {        // Create a collection of Locale objects to search        Collection<Locale> locales = new ArrayList<>();        locales.add(Locale.forLanguageTag("en-GB"));        locales.add(Locale.forLanguageTag("ja"));        locales.add(Locale.forLanguageTag("zh-cmn-Hans-CN"));        locales.add(Locale.forLanguageTag("en-US"));        // Express the user's preferences with a Language Priority List        String ranges = "en-US;q=1.0,en-GB;q=0.5,fr-FR;q=0.0";        List<Locale.LanguageRange> languageRanges = Locale.LanguageRange.parse(ranges);        // Find the BEST match, and return just one result        Locale result = Locale.lookup(languageRanges,locales);        System.out.println(result.toString());    }}

In contrast to the filtering examples, the lookup demo in Example 6 returns the one object that is the best match (en-US in this case). For completeness, Example 7 shows how to perform the same lookup usingString objects.

Example 7:

package languagetagdemo;import java.util.Locale;import java.util.Collection;import java.util.List;import java.util.ArrayList;public class LanguageTagDemo {    public static void main(String[] args) {        // Create a collection of String objects to match against        Collection<String> tags = new ArrayList<>();        tags.add("en-GB");        tags.add("ja");        tags.add("zh-cmn-Hans-CN");        tags.add("en-US");        // Express user's preferences with a Language Priority List        String ranges = "en-US;q=1.0,en-GB;q=0.5,fr-FR;q=0.0";        List<Locale.LanguageRange> languageRanges = Locale.LanguageRange.parse(ranges);        // Find the BEST match, and return just one result        String result = Locale.lookupTag(languageRanges, tags);        System.out.println(result);    }}

This example returns the single object that best matches the user's Language Priority List.