net.sf.okapi.common

## Class LocaleId

- java.lang.Object
- - net.sf.okapi.common.LocaleId

- All Implemented Interfaces:
    java.lang.Comparable<java.lang.Object>

      public final class LocaleId
      extends java.lang.Object
      implements java.lang.Comparable<java.lang.Object>

  Holds the normalized identifier for a given language/locale.

- - ### Field Summary

    Fields
    Modifier and Type | Field and Description
    --- | ---
    `static LocaleId` | `ARABIC` LocaleId constant for "ar".
    `static LocaleId` | `CHINA_CHINESE` LocaleId constant for "zh-cn".
    `static LocaleId` | `EMPTY` An empty locale.
    `static LocaleId` | `ENGLISH` LocaleId constant for "en".
    `static LocaleId` | `FRENCH` LocaleId constant for "fr".
    `static LocaleId` | `GERMAN` LocaleId constant for "de".
    `static LocaleId` | `ITALIAN` LocaleId constant for "it".
    `static LocaleId` | `JAPANESE` LocaleId constant for "ja".
    `static LocaleId` | `KOREAN` LocaleId constant for "ko".
    `static LocaleId` | `PORTUGUESE` LocaleId constant for "pt".
    `static LocaleId` | `RUSSIAN` LocaleId constant for "ru".
    `static LocaleId` | `SPANISH` LocaleId constant for "es".
    `static LocaleId` | `TAIWAN_CHINESE` LocaleId constant for "zh-tw".

  - ### Constructor Summary

    Constructors
    Constructor and Description
    `LocaleId(java.util.Locale loc)` Creates a new LocaleId for the given Java Locale.
    `LocaleId(java.lang.String language)` Creates a new LocaleId for a given language code.
    `LocaleId(java.lang.String locId, boolean normalize)` Creates a new LocaleId object from a locale identifier.
    `LocaleId(java.lang.String language, java.lang.String region)` Creates a new LocaleId for a given language code and region code.
    `LocaleId(java.lang.String language, java.lang.String region, java.lang.String userPart)` Creates a new LocaleId for a given language code, region code, and a user part.

  - ### Method Summary

    Methods
    Modifier and Type | Method and Description
    --- | ---
    `LocaleId` | `clone()` Returns a clone of this LocaleId.
    `int` | `compareTo(java.lang.Object arg)` Compares this LocaleId with a given object.
    `static java.util.List<LocaleId>` | `convertToLocaleIds(java.util.List<java.lang.String> languageCodes)` Converts a list of language codes into `LocaleId`s
    `boolean` | `equals(java.lang.Object arg)` Indicates if a given object is equal to this localeId object.
    `static LocaleId` | `fromBCP47(java.lang.String langtag)` Creates a new LocaleId from a BCP-47 language tag.
    `static LocaleId` | `fromPOSIXLocale(java.lang.String locId)` Creates a new LocaleId from a POSIX locale identifier.
    `static LocaleId` | `fromString(java.lang.String locId)` Creates a new LocaleId from a locale identifier (and validate it).
    `static LocaleId[]` | `getAvailableLocales()` Gets an array of the LocaleId objects for all the Java locales installed on the system.
    `java.lang.String` | `getLanguage()` Gets the language code for this LocaleId.
    `java.lang.String` | `getRegion()` Gets the region code for this LocaleId.
    `java.lang.String` | `getUserPart()` Gets the user part of this LocaleId.
    `int` | `hashCode()` Returns a hash code value for this LocaleId.
    `static boolean` | `isBidirectional(LocaleId locId)` Indicates if a given locale usually uses a bi-directional script.
    `static java.lang.String` | `replaceVariables(java.lang.String input, LocaleId srcLoc, LocaleId trgLoc)` Replaces the locale/language variables in a given input string by their runtime values.
    `static java.lang.String` | `replaceVariables(java.lang.String input, java.lang.String srcLoc, java.lang.String trgLoc)` Replaces the locale/language variables in a given input string by their runtime values.
    `boolean` | `sameLanguageAs(LocaleId other)` Indicates if the language of a given LocaleId is the same as the one of this LocaleId.
    `boolean` | `sameLanguageAs(java.lang.String langCode)` Indicates if a given string has the same language as the one of this LocaleId.
    `boolean` | `sameRegionAs(LocaleId other)` Indicates if the region of a given LocaleId is the same as the one of this LocaleId.
    `boolean` | `sameRegionAs(java.lang.String langCode)` Indicates if a given string has the same region as the one of this LocaleId.
    `boolean` | `sameUserPartAs(LocaleId other)` Indicates if the user part of a given LocaleId is the same as the one of this LocaleId.
    `boolean` | `sameUserPartAs(java.lang.String langCode)` Indicates if a given string has the same user part as the one of this LocaleId.
    `static java.lang.String[]` | `splitLanguageCode(java.lang.String language)` Splits a given ISO language tag (e.g.
    `java.lang.String` | `toBCP47()` Gets the BCP-47 language tag for this LocaleId.
    `java.util.Locale` | `toJavaLocale()` Creates a new Java Locale object from this LocaleId.
    `java.lang.String` | `toPOSIXLocaleId()` Gets a POSIX locale identifier for this LocaleId.
    `java.lang.String` | `toString()` Gets the string representation of the LocaleId.

    - ### Methods inherited from class java.lang.Object

      `finalize, getClass, notify, notifyAll, wait, wait, wait`

- - ### Field Detail

    - #### EMPTY

          public static final LocaleId EMPTY

      An empty locale.

    - #### ARABIC

          public static final LocaleId ARABIC

      LocaleId constant for "ar".

    - #### CHINA_CHINESE

          public static final LocaleId CHINA_CHINESE

      LocaleId constant for "zh-cn".

    - #### TAIWAN_CHINESE

          public static final LocaleId TAIWAN_CHINESE

      LocaleId constant for "zh-tw".

    - #### ENGLISH

          public static final LocaleId ENGLISH

      LocaleId constant for "en".

    - #### FRENCH

          public static final LocaleId FRENCH

      LocaleId constant for "fr".

    - #### GERMAN

          public static final LocaleId GERMAN

      LocaleId constant for "de".

    - #### ITALIAN

          public static final LocaleId ITALIAN

      LocaleId constant for "it".

    - #### JAPANESE

          public static final LocaleId JAPANESE

      LocaleId constant for "ja".

    - #### KOREAN

          public static final LocaleId KOREAN

      LocaleId constant for "ko".

    - #### PORTUGUESE

          public static final LocaleId PORTUGUESE

      LocaleId constant for "pt".

    - #### RUSSIAN

          public static final LocaleId RUSSIAN

      LocaleId constant for "ru".

    - #### SPANISH

          public static final LocaleId SPANISH

      LocaleId constant for "es".

  - ### Constructor Detail

    - #### LocaleId

          public LocaleId(java.lang.String locId,
                  boolean normalize)

      Creates a new LocaleId object from a locale identifier.
      Parameters:
        `locId` - a LocaleId string
        `normalize` - true if it needs to be normalized the string, false to use as-it. When use as-it, the identifier is expected to be in lower-cases and use '-' for separator.
      Throws:
        `java.lang.IllegalArgumentException` - if the argument in invalid.

    - #### LocaleId

          public LocaleId(java.lang.String language)

      Creates a new LocaleId for a given language code. This constructor does not take a locale identifier as argument, just a language identifier. Use `LocaleId(String, boolean)` to create a new LocaleId from a locale identifier.
      Parameters:
        `language` - the language code (e.g. "de" for German).
      Throws:
        `java.lang.IllegalArgumentException` - if the argument in invalid.

    - #### LocaleId

          public LocaleId(java.lang.String language,
                  java.lang.String region)

      Creates a new LocaleId for a given language code and region code.
      Parameters:
        `language` - the language code (e.g. "es" for Spanish).
        `region` - the region code (e.g. "es" for Spain or "005" for South America. This parameter is ignored if null or empty.
      Throws:
        `java.lang.IllegalArgumentException` - if the argument in invalid.

    - #### LocaleId

          public LocaleId(java.lang.String language,
                  java.lang.String region,
                  java.lang.String userPart)

      Creates a new LocaleId for a given language code, region code, and a user part.
      Parameters:
        `language` - the language code (e.g. "es" for Spanish).
        `region` - the region code (e.g. "es" for Spain or "005" for South America.
        `userPart` - the user part of locale. The latter two parameters are ignored if null or empty.
      Throws:
        `java.lang.IllegalArgumentException` - if the argument in invalid.

    - #### LocaleId

          public LocaleId(java.util.Locale loc)

      Creates a new LocaleId for the given Java Locale.
      Parameters:
        `loc` - the Java Locale object to use.
      Throws:
        `java.lang.IllegalArgumentException` - if the argument in invalid.

  - ### Method Detail

    - #### replaceVariables

          public static java.lang.String replaceVariables(java.lang.String input,
                                          LocaleId srcLoc,
                                          LocaleId trgLoc)

      Replaces the locale/language variables in a given input string by their runtime values. If one of the locale passed is null, its corresponding variables are replaced by an empty string.
      Parameters:
        `input` - the string with the variables.
        `srcLoc` - the source locale code (can be null).
        `trgLoc` - the target locale code (can be null).
      Returns:
        the modified string.

    - #### replaceVariables

          public static java.lang.String replaceVariables(java.lang.String input,
                                          java.lang.String srcLoc,
                                          java.lang.String trgLoc)

      Replaces the locale/language variables in a given input string by their runtime values. If one of the locale passed is null, its corresponding variables are replaced by an empty string.
      Parameters:
        `input` - the string with the variables.
        `srcLoc` - the source locale code (can be null).
        `trgLoc` - the target locale code (can be null).
      Returns:
        the modified string.

    - #### toString

          public java.lang.String toString()

      Gets the string representation of the LocaleId.
      Overrides:
        `toString` in class `java.lang.Object`
      Returns:
        the string representation of the LocaleId.

    - #### clone

          public LocaleId clone()

      Returns a clone of this LocaleId. Because LocaleId are immutable objects this method returns the same LocaleId.
      Overrides:
        `clone` in class `java.lang.Object`
      Returns:
        the same LocaleId (because it is immutable).

    - #### hashCode

          public int hashCode()

      Returns a hash code value for this LocaleId.
      Overrides:
        `hashCode` in class `java.lang.Object`
      Returns:
        the hash code value for this LocaleId.

    - #### equals

          public boolean equals(java.lang.Object arg)

      Indicates if a given object is equal to this localeId object.
      Overrides:
        `equals` in class `java.lang.Object`
      Parameters:
        `arg` - the object to compare. This can be a LocaleId object or a string. Any other object will always return false. If the parameter is a string it is normalized before being compared.
      Returns:
        true if the parameter is the same object, or if it is a LocaleId with the same identifier, or if it is a string equals to the identifier. False otherwise.

    - #### compareTo

          public int compareTo(java.lang.Object arg)

      Compares this LocaleId with a given object.
      Specified by:
        `compareTo` in interface `java.lang.Comparable<java.lang.Object>`
      Parameters:
        `arg` - the object to compare. If the parameter is a string it is normalized before being compared.
      Returns:
        1 if the parameter is null. If the parameter is a LocaleId or a string, the return is the same as the return of a comparison between the identifier of this LocaleId and the string representation of the argument. Otherwise the return is 1;

    - #### fromString

          public static LocaleId fromString(java.lang.String locId)

      Creates a new LocaleId from a locale identifier (and validate it). Calling this method is the same as calling `new LocaleId(locId, true);`
      Parameters:
        `locId` - the locale identifier to use (it will be normalized).
      Returns:
        a new localeId object from the given identifier.
      Throws:
        `java.lang.IllegalArgumentException` - if the argument is invalid.

    - #### fromPOSIXLocale

          public static LocaleId fromPOSIXLocale(java.lang.String locId)

      Creates a new LocaleId from a POSIX locale identifier.
      Parameters:
        `locId` - the POSIX locale identifier (e.g. "de-at.UTF-8@EURO")
      Returns:
        a new LocaleId or null if an error occurred.
      Throws:
        `java.lang.IllegalArgumentException` - if the argument is invalid.

    - #### toPOSIXLocaleId

          public java.lang.String toPOSIXLocaleId()

      Gets a POSIX locale identifier for this LocaleId. For example: "af-za" returns "af_ZA".
      Returns:
        the corresponding POSIX locale identifier for this LocaleId.

    - #### fromBCP47

          public static LocaleId fromBCP47(java.lang.String langtag)

      Creates a new LocaleId from a BCP-47 language tag.
      Parameters:
        `langtag` - the language tag to use (e.g. "fr-CA")
      Returns:
        a new LocaleId, or null if an error occurred.

    - #### toBCP47

          public java.lang.String toBCP47()

      Gets the BCP-47 language tag for this LocaleId.
      Returns:
        the BCP-47 language tag for the given LocaleId.

    - #### toJavaLocale

          public java.util.Locale toJavaLocale()

      Creates a new Java Locale object from this LocaleId.
      Returns:
        a new Java Locale object based on the best match for the given LocaleId, or null if an error occurred.

    - #### getLanguage

          public java.lang.String getLanguage()

      Gets the language code for this LocaleId.
      Returns:
        the language code.

    - #### getRegion

          public java.lang.String getRegion()

      Gets the region code for this LocaleId.
      Returns:
        the region code or null if there is none or if an error occurs.

    - #### getUserPart

          public java.lang.String getUserPart()

      Gets the user part of this LocaleId.
      Returns:
        the user part or null if there is none or if an error occurs.

    - #### sameLanguageAs

          public boolean sameLanguageAs(LocaleId other)

      Indicates if the language of a given LocaleId is the same as the one of this LocaleId. For example: "en" and "en-us" returns true, "es-es" and "ca-es" return false.
      Parameters:
        `other` - the LocaleId object to compare.
      Returns:
        true if the languages of two given LocaleIds are the same.

    - #### sameLanguageAs

          public boolean sameLanguageAs(java.lang.String langCode)

      Indicates if a given string has the same language as the one of this LocaleId. For example: "en" and "en-us" returns true, "es-es" and "ca-es" return false.
      Parameters:
        `langCode` - the string to compare.
      Returns:
        true if the languages of both objects are the same.

    - #### sameRegionAs

          public boolean sameRegionAs(LocaleId other)

      Indicates if the region of a given LocaleId is the same as the one of this LocaleId. For example: "es-us" and "en-us" returns true, "es-es" and "es-us" return false.
      Parameters:
        `other` - the LocaleId object to compare.
      Returns:
        true if the region parts of two given LocaleIds are the same.

    - #### sameRegionAs

          public boolean sameRegionAs(java.lang.String langCode)

      Indicates if a given string has the same region as the one of this LocaleId. For example: "es-us" and "en-us" returns true, "es-es" and "es-us" return false.
      Parameters:
        `langCode` - the string to compare.
      Returns:
        true if the region parts of both objects are the same.

    - #### sameUserPartAs

          public boolean sameUserPartAs(LocaleId other)

      Indicates if the user part of a given LocaleId is the same as the one of this LocaleId. For example: "es-us-x-win" and "en_us@win" returns true, "es_us@mac" and "es_us@ats" return false.
      Parameters:
        `other` - the LocaleId object to compare.
      Returns:
        true if the region parts of two given LocaleIds are the same.

    - #### sameUserPartAs

          public boolean sameUserPartAs(java.lang.String langCode)

      Indicates if a given string has the same user part as the one of this LocaleId. For example: "es-us-x-win" and "en-us@win" returns true, "es-us@mac" and "es-us@ats" return false.
      Parameters:
        `langCode` - the string to compare.
      Returns:
        true if the region parts of both objects are the same.

    - #### getAvailableLocales

          public static LocaleId[] getAvailableLocales()

      Gets an array of the LocaleId objects for all the Java locales installed on the system.
      Returns:
        an array of the LocaleId objects for all the available Java locales.

    - #### splitLanguageCode

          public static java.lang.String[] splitLanguageCode(java.lang.String language)

      Splits a given ISO language tag (e.g. "fr-ca") into its components. Use this method when working directly with an `LocaleId` object is not desirable. This method supports only simple ISO codes (not complex BCP-47 tags).
      Parameters:
        `language` - the language code to process.
      Returns:
        an array of two strings: 0=language, 1=region/country (or empty)

    - #### isBidirectional

          public static boolean isBidirectional(LocaleId locId)

      Indicates if a given locale usually uses a bi-directional script.

      Note that this is not perfect as some languages use several scripts.

      Parameters:
        `locId` - the locale to check.
      Returns:
        true if the locale uses a bi-directional script.

    - #### convertToLocaleIds

          public static java.util.List<LocaleId> convertToLocaleIds(java.util.List<java.lang.String> languageCodes)

      Converts a list of language codes into `LocaleId`s
      Parameters:
        `languageCodes` - the list of codes.
      Returns:
        the list of `LocaleId` objects created.