senselogic.sitevision.api.i18n

Interface LocaleUtil

@Requireable(value="LocaleUtil")
public interface LocaleUtil

Locale utility interface.

Note! Sitevision supports a few Locales that uses 3 char ISO-639 language codes. These are not automatically handled by Java. Sitevision also supports a few 2 char language codes that isn't natively supported by Java in most regions of the world. This interface handles all Locales supported/installed by Java and all "custom" Locales that Sitevision has added. Here are some examples for such Locales:

• Northern Sami, i.e. new Locale("se", "SE")
• South Sami, i.e. new Locale("sma", "SE")
• Lule Sami, i.e. new Locale("smj", "SE")
• Soranî, i.e. new Locale("ckb", "IR")
• Farsi, i.e. new Locale("fa", "IR")
• Kurmanji, i.e. new Locale("ku", "TR")

Information about Supported Locales in JDK 8.

An instance of the Sitevision class implementing this interface can be obtained via Utils.getLocaleUtil(). See Utils for how to obtain an instance of the Utils interface.

Since:

Sitevision 3.6

Author:

Magnus Lövgren

See Also:

PortletContextUtil.getCurrentLocale(), NodeResolverUtil.getLocaleResolver()

Method Summary

Modifier and Type	Method and Description
List<Locale>	getAvailableLocales() Gets an immutable list of all available Locales (installed Java Locales and custom ones added by Sitevision).
String	getLanguageTag(Locale aLocale) Returns the IETF BCP 47 language tag value for a Locale.
Locale	getLocaleByString(String aLocaleString) Returns the Locale for a language tag or a String that contains language or language + country ("en-US" or "en" or "en_US").
String	getLocalizedLanguageName(Locale aLocale, Locale aDisplayLocale) Gets the localized language name for a specified Locale.
String	getLocalizedLanguageNameByString(String aLocaleString, Locale aDisplayLocale) Gets the localized language name for a Locale that is resolved via a specified locale string.
String	getNativeLanguageName(Locale aLocale) Gets the native language name for a specified Locale.
String	getNativeLanguageNameByString(String aLocaleString) Gets the native language name for a Locale that is resolved via a specified locale string.
String	getNormalizedLanguage(Locale aLocale) Returns the normalized language for a specified Locale.
boolean	isRTL(Locale aLocale) Checks if a locale has writing direction Right-To-Left (RTL).
Locale	resolveCountryLocale(Locale aLocale) Gets a Locale with language and country for a (typically language-only) Locale.

Method Detail

getAvailableLocales

List<Locale> getAvailableLocales()

Gets an immutable list of all available Locales (installed Java Locales and custom ones added by Sitevision).

Note! The returned List is immutable/unmodifiable, i.e. you must create a copy if you want to modify it (e.g. sort).

Below is an example of how to display some info about all locales via server-side Javascript:

    (function() {
       var localeUtil = require('LocaleUtil'),
          locales = localeUtil.getAvailableLocales(),
          count = locales.size(),
          currentLocale = require('PortletContextUtil').getCurrentLocale(),
          locale, i;

       out.println('<table>');
       out.println('<tr>');
       out.println('   <th>Language</th>');
       out.println('   <th>Country</th>');
       out.println('   <th>Language Tag</th>');
       out.println('   <th>Native language name</th>');
       out.println('   <th>Localized language name</th>');
       out.println('   <th>Directionality</th>');
       out.println('</tr>');
       for (i = 0; i < count; i++) {
          locale = locales.get(i);
          out.println('<tr>');
          out.println('   <td>' + localeUtil.getNormalizedLanguage(locale) + '</td>');
          out.println('   <td>' + locale.getCountry() + '</td>');
          out.println('   <td>' + localeUtil.getLanguageTag(locale) + '</td>');
          out.println('   <td>' + localeUtil.getNativeLanguageName(locale) + '</td>');
          out.println('   <td>' + localeUtil.getLocalizedLanguageName(locale, currentLocale) + '</td>');
          out.println('   <td>' + (localeUtil.isRTL(locale) ? 'RTL' : 'LTR') + '</td>');
          out.println('</tr>');
       }
       out.println('</table>');
    }());

Returns:

a immutable/unmodifiable list of all available Locales (i.e. all Locales installed by Java and all custom Locales added by Sitevision)

Since:

Sitevision 4.1

getNativeLanguageName

String getNativeLanguageName(Locale aLocale)

Gets the native language name for a specified Locale.

Some examples:

• A Swedish Locale will return Svenska
• A German Locale will return Deutsch
• A Northern Sami Locale will return Davvisámegiella

Parameters:

aLocale - the locale

Returns:

the native language name for aLocale, or null if aLocale is null

getLocalizedLanguageName

String getLocalizedLanguageName(Locale aLocale,
                                Locale aDisplayLocale)

Gets the localized language name for a specified Locale.

Some examples:

• A Swedish aLocale and an English aDisplayLocale will return Swedish
• An English aLocale and a Swedish aDisplayLocale will return Engelska
• A German aLocale and a Swedish aDisplayLocale will return Tyska
• A German aLocale and an English aDisplayLocale will return German

Parameters:

aLocale - the locale to get the language name for

aDisplayLocale - the locale that should be used when displaying the language name of aLocale

Returns:

the localized language name for aLocale, or null if aLocale is null

getNativeLanguageNameByString

String getNativeLanguageNameByString(String aLocaleString)

Gets the native language name for a Locale that is resolved via a specified locale string.

This method can be seen as a convenience method that combines the getLocaleByString(String) method and the getNativeLanguageName(java.util.Locale) method to resolve a Locale and get the native language name. But this is not strictly true. This method will handle all all well-formed locale strings that starts with a valid language code used by a supported locale (even though the "full" locale string might actually refer to a non-supported locale).

Some examples of this forgiving/lenient behaviour:

• "rmy-RO" matches a supported locale (Romani in Romania) and will return the native name for the "rmy" language.
• "rmy_RO" matches a supported locale (Romani in Romania) and will return the native name for the "rmy" language.
• "rmy" does NOT match the supported locale "rmy-RO"/"rmy_RO" but will still return the native name for the "rmy" language.
• "rmy-SE" does NOT match the supported locale "rmy-RO" but will still return the native name for the "rmy" language.
• "rmy_SE" does NOT match the supported locale "rmy_RO" but will still return the native name for the "rmy" language.

Parameters:

aLocaleString - a language tag ("en-US") or string that contains language only ("en") or language and country ("en_US"), typically what you will get as result of Locale.toString()

Returns:

the native language name for the aLocale that matches aLocaleString, or null if aLocaleString is null, whitespace only or doesn't match a supported Locale

getLocalizedLanguageNameByString

String getLocalizedLanguageNameByString(String aLocaleString,
                                        Locale aDisplayLocale)

Gets the localized language name for a Locale that is resolved via a specified locale string.

This is a convenience method that combines the getLocaleByString(String) method and the getLocalizedLanguageName(java.util.Locale, java.util.Locale) method to resolve a Locale and get the localized language name.

Parameters:

aLocaleString - a string that contains language ("en") or language and country ("en_US"), typically what you will get as result of Locale.toString()

aDisplayLocale - the locale that should be used when displaying the language name of the Locale resolved by aLocaleString

Returns:

the localized language name for the aLocale that matches aLocaleString, or null if aLocaleString is null, whitespace only or doesn't match a supported Locale

getLocaleByString

Locale getLocaleByString(String aLocaleString)

Returns the Locale for a language tag or a String that contains language or language + country ("en-US" or "en" or "en_US").

A toString() on a english american locale returns the String "en_US", but to create a locale from that string you can NOT just create it by doing: new Locale("en_US"). You must split language (en) and country (US) since the proper way of creating the Locale is: new Locale("en", "US").

Some examples of accepted locale strings:

• Swedish language tag: "sv-SE" and locale strings: "sv", "sv_SE"
• German language tag: "de-DE" and locale strings: "de", "de_DE"
• Northern Sami language tag: "se-SE" and locale string: "se_SE"

Note! This method only handles supported Locale's, i.e. Locales available via getAvailableLocales().

Parameters:

aLocaleString - a language tag or the toString() value of a Locale (i.e. a String with a lowercased language - or a lowercased language and uppercased country, separated with underscore).

Returns:

a Locale matching aLocaleString, or null if aLocaleString is null, whitespace only or doesn't match a supported Locale

getLanguageTag

String getLanguageTag(Locale aLocale)

Returns the IETF BCP 47 language tag value for a Locale.

Language tags are used to indicate the language of texts or other items in HTML and XML documents. The language tag syntax is defined by the IETF BCP 47 and exemplified by W3C internationalization in Language tags in HTML and XML.

This method supports both the Java default locales and the custom-defined ones in Sitevision (such as Northern Sami). It produces a well-formatted BCP 47 value for a specified Locale but the language and region are not verified against the IANA language subtag registry.

Some output examples:

• Swedish locale (language "sv", country "SE"): "sv-SE"
• American english locale (language "en", country "US"): "en-US"
• Canadian french locale (language "fr", country "CA"): "fr-CA"

Parameters:

aLocale - a locale

Returns:

the aLocale formatted according to BCP 47, or null if aLocale is null

getNormalizedLanguage

String getNormalizedLanguage(Locale aLocale)

Returns the normalized language for a specified Locale.

Java uses old ISO language codes for for language codes that have changed. For instance: the legacy ISO language code for Yiddish is "ji", but that was changed to "yi" 1989. This method compensates for Javas legacy considerations and returns the new ISO language codes instead.

Parameters:

aLocale - a locale

Returns:

the normalized language for the locale, or null if the locale is null

Since:

Sitevision 4.5.1

isRTL

boolean isRTL(Locale aLocale)

Checks if a locale has writing direction Right-To-Left (RTL).

Most languages have a clear writing direction, typically Left-To-Right (LTR). Though, some languages has mixed writing directions (e.g. text is RTL but numbers are LTR) and some languages is written with different symbols (e.g. Latin, Arabic) in different regions. This method will return true for such complex/mixed languages if the official writing direction is RTL or if RTL is used by the majority of the native language writers.

This method supports the Java default locales and the custom-defined ones in Sitevision (such as Northern Sami). It also supports locales that aren't officially supported by Sitevision (i.e. not present in getAvailableLocales()). The direction of the first char in the locales native name (as of getNativeLanguageName(Locale)) is used to determine if the locale is LTR or RTL for such (unofficial) locales.

Parameters:

aLocale - a locale

Returns:

true if aLocale has Right-To-Left (RTL) writing direction, false otherwise (i.e. false indicates LTR)

Since:

Sitevision 4.3

resolveCountryLocale

Locale resolveCountryLocale(Locale aLocale)

Gets a Locale with language and country for a (typically language-only) Locale.

Replacement of language-only locales

Locale/language	Replacement
Swedish (sv)	Sweden (sv-SE)
Norwegian (no)	Norway (no-NO)
Danish (da)	Denmark (da-DK)
Finnish (fi)	Finland (fi-FI)
Icelandic (is)	Iceland (is-IS)
Belarusian (be)	Belarus (be-BY)
Bulgarian (bg)	Bulgaria (bg-BG)
Catalan (ca)	Spain (ca-ES)
Czech (cs)	Czech Republic (cs-CZ)
Estonian (et)	Estonia (et-EE)
Irish (ga)	Ireland (ga-IE)
Hebrew (he) and (iw)	Israel (he-IL)
Hindi (hi)	India (hi-IN)
Croatian (hr)	Croatia (hr-HR)
Indonesian (id) and (in)	Indonesia (id-ID)
Italian (it)	Italy (it-IT)
Japanese (ja)	Japan (ja-JP)
Lithuanian (lt)	Lithuania (lt-LT)
Latvian (lv)	Latvia (lv-LV)
Malay (ms)	Malaysia (ms-MY)
Maltese (mt)	Malta (mt-MT)
Polish (pl)	Poland (pl-PL)
Romanian (ro)	Romania (ro-RO)
Slovak (sk)	Slovakia (sk-SK)
Slovenian (sl)	Slovenia (sl-SI)
Albanian (sq)	Albania (sq-AL)
Thai (th)	Thailand (th-TH)
Turkish (tr)	Turkey (tr-TR)
Ukranian (uk)	Ukraine (uk-UA)
Vietnamese (vi)	Vietnam (vi-VN)

Important language-only note! There are many language-only locales that can not be resolved (i.e. the language is officially spoken in multiple countries). This method will return null for such locales. For example:

• English (en)
• French (fr)
• German (de)
• Dutch (nl)
• Spanish (es)
• Russian (ru)
• Arabic (ar)
• Farsi (fa)
• ...

Parameters:

aLocale - a Locale, typically a language-only Locale

Returns:

the corresponding locale with country, or null if no corresponding locale could be found

Since:

Sitevision 6.1