Package resources

Class Language

  • All Implemented Interfaces:
    java.lang.Iterable<java.lang.String>
    public class Language
extends java.lang.Object
implements java.lang.Iterable<java.lang.String>
    A language object manages language-related resources for a particular locale. This includes a table of strings (that can be expanded using resource bundles), a pluralizer, and a string a collator. Other resources can be located using localized strings in the string table, or searching for matching resource files using getResourceChain(java.lang.String, java.lang.String). Static methods string(java.lang.String) and gstring(java.lang.String) provide quick access to strings defined in the default user interface and game languages, respectively.

    More than one language instance can be defined for a locale, and they can either be kept isolated from each other or linked together in an inheritance chain. When localizing a plug-in, you can either add your strings to the default interface and/or game languages (in which case you must avoid conflicting key names) or create your own. The best option is to create your own and set the default instance as their parents, although this takes a little more work.

    Since:
    3.0
    Author:
    Chris Jennings

    • Nested Class Summary

      Nested Classes 
      Modifier and Type Class Description
      static class  Language.LocalizedFileName
      Splits a file name into tokens to extract locale information.

    • Constructor Summary

      Constructors 
      Constructor Description
      Language​(java.lang.String loc)
      Create an empty language resource for a locale described by a locale description, such as "en_CA".
      Language​(java.util.Locale loc)
      Create an empty language resource for a locale.

    • Method Summary

      All Methods Static Methods Instance Methods Concrete Methods 
      Modifier and Type Method Description
      static void addGameLocale​(java.util.Locale loc)
      Marks the locale loc as a "preferred locale" for game language purposes.
      static void addInterfaceLocale​(java.util.Locale loc)
      Marks the locale loc as a "preferred locale" for interface language purposes.
      void addStrings​(java.lang.String baseResource)
      Adds strings from a new set of resource files to this language.
      java.lang.String get​(java.lang.String key)
      Returns a string defined in this language instance.
      java.lang.String get​(java.lang.String key, java.lang.Object... args)
      Returns a formatted string defined in this language.
      java.text.Collator getCollator()
      Returns a Collator that can be used to sort strings in this language.
      static Language getGame()
      Returns the shared Language instance that represents the game language.
      static java.util.Locale getGameLocale()
      Returns the game locale.
      static java.util.Locale[] getGameLocales()
      Returns a sorted array of the available game locales.
      static javax.swing.Icon getIconForCountry​(java.util.Locale loc)
      Returns a flag icon for the country part of locale loc.
      static javax.swing.Icon getIconForLanguage​(java.util.Locale loc)
      Returns an icon for the language part of locale loc.
      static javax.swing.Icon getIconForLocale​(java.util.Locale loc)
      Returns an icon that represents the language and country of a locale.
      static Language getInterface()
      Returns the shared Language instance that represents the UI language.
      static java.util.Locale getInterfaceLocale()
      Returns the user interface locale.
      static java.util.Locale[] getInterfaceLocales()
      Returns a sorted array of the available interface locales.
      java.util.Locale getLocale()
      Returns the locale used by this language instance.
      static java.util.Locale[] getLocales()
      Returns a sorted array of all available locales.
      Language getParent()
      Returns this language's parent, or null if it has no parent.
      IntegerPluralizer getPluralizer()
      Returns a pluralizer for strings in the this language.
      java.lang.String[] getResourceChain​(java.lang.String baseName, java.lang.String suffix)
      Returns an array of resources that match the requested file name from least to most specialized for the locale's language.
      static java.lang.String gstring​(java.lang.String key)
      Returns a string looked up with the default game language.
      static java.lang.String gstring​(java.lang.String key, java.lang.Object... args)
      Formats and returns a format string looked up with the default game language.
      boolean isKeyDefined​(java.lang.String key)
      Returns true if the specified key if defined.
      static boolean isLocaleDescriptionValid​(java.lang.String description)
      Returns true if a locale description represents a valid locale.
      java.util.Iterator<java.lang.String> iterator()
      Returns an iterator that iterates over the keys in this language (not including any parents).
      java.util.Set<java.lang.String> keySet()
      Returns a copy of all of the keys defined in this language (not including any parents).
      static java.util.Locale parseLocaleDescription​(java.lang.String code)
      Parses a locale description in ll_CC format and returns the Locale.
      void set​(java.lang.String key, java.lang.String value)
      Explicitly sets a key to a fixed value, overriding the result that would be obtained from the loaded string tables.
      static void setGameLocale​(java.util.Locale game)
      Sets the locale used for the shared game language.
      static void setInterfaceLocale​(java.util.Locale ui)
      Sets the locale used for the shared interface language.
      void setLocale​(java.util.Locale loc)
      Changes the locale used by this language instance.
      void setParent​(Language parent)
      Sets this language's parent.
      java.lang.String str​(java.lang.String key)
      A synonym for get(java.lang.String) that can be called from scripts without specifying an overload.
      static java.lang.String string​(java.lang.String key)
      Returns a string looked up with the default interface language.
      static java.lang.String string​(java.lang.String key, java.lang.Object... args)
      Formats and returns a format string looked up with the default interface language.
      java.lang.String toString()
      Returns the string representation of this language, a string describing the language's locale.

      • Methods inherited from class java.lang.Object

        clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

      • Methods inherited from interface java.lang.Iterable

        forEach, spliterator

    • Constructor Detail

      • Language

        public Language​(java.util.Locale loc)
        Create an empty language resource for a locale. If loc is null, the current UI locale is used.
        Parameters:
        loc - the locale that this language instance is based on
        See Also:
        setLocale(java.util.Locale)

      • Language

        public Language​(java.lang.String loc)
        Create an empty language resource for a locale described by a locale description, such as "en_CA".

    • Method Detail

      • setParent

        public void setParent​(Language parent)
        Sets this language's parent. If a string cannot be found in this language's string table, and a non-null parent is defined, then the chain of parents will be searched to locate a definition.
        Parameters:
        parent - the new parent to set; if null the existing parent (if any) is removed
        Throws:
        java.lang.IllegalArgumentException - if setting the parent would create a cycle (a language is directly or indirectly its own ancestor)

      • getParent

        public Language getParent()
        Returns this language's parent, or null if it has no parent. The language's parent is consulted if this language does not define a string.
        Returns:
        the parent instance, or null

      • setLocale

        public void setLocale​(java.util.Locale loc)
        Changes the locale used by this language instance. If the supplied locale is null, the default locale is used. The supplied locale must include a language and may optionally include a region (country).

        Variants are not supported. If the supplied locale includes a variant, the variant part of the locale will be dropped silently. (In this case, getLocale() will return a value that is not equal to the locale passed to the method.)

        Parameters:
        loc - the new locale to use

      • getLocale

        public java.util.Locale getLocale()
        Returns the locale used by this language instance.
        Returns:
        the language locale

      • addStrings

        public void addStrings​(java.lang.String baseResource)
        Adds strings from a new set of resource files to this language. The resource files to be loaded will be determined as if by calling getResourceChain(java.lang.String, java.lang.String). If the base resource name includes an extension (a suffix starting with a '.' character), that extension will be used to locate the resource files. If the base resource name does not include an extension, the extension .properties will be used.

        To prevent the accidental replacement of strings from the main application, this method will not alter the value of string keys that are already defined. If you wish to replace the value of an existing key, you can do so using the set(java.lang.String, java.lang.String) method.

        Parameters:
        baseResource - the resource path to the base file of a set of string table files

      • get

        public java.lang.String get​(java.lang.String key)
        Returns a string defined in this language instance.
        Parameters:
        key - the key for the string to retrieve
        Returns:
        the localized string, or [MISSING: key]

      • str

        public java.lang.String str​(java.lang.String key)
        A synonym for get(java.lang.String) that can be called from scripts without specifying an overload.
        Parameters:
        key - the key for the string to retrieve
        Returns:
        the localized string, or [MISSING: key]

      • get

        public java.lang.String get​(java.lang.String key,
                            java.lang.Object... args)
        Returns a formatted string defined in this language. Formatting flags in the localized string will be filled in using the supplied arguments. The formatting flags accepted by the method are exactly the same as those supported by String.format (similar to sprintf in C).
        Parameters:
        key - the key for the localized formatting template
        args - the arguments to use to fill in the formatting template
        Returns:
        the localized, formatted string or [MISSING: key]

      • isKeyDefined

        public boolean isKeyDefined​(java.lang.String key)
        Returns true if the specified key if defined.
        Parameters:
        key - the name of the key to test
        Returns:
        true if the key has a value

      • set

        public void set​(java.lang.String key,
                java.lang.String value)
        Explicitly sets a key to a fixed value, overriding the result that would be obtained from the loaded string tables. If value is null, any value previously set with this method is removed.
        Parameters:
        key - the key to affect
        value - the new string value
        Throws:
        java.lang.NullPointerException - if the key is null

      • keySet

        public java.util.Set<java.lang.String> keySet()
        Returns a copy of all of the keys defined in this language (not including any parents).
        Returns:
        a set of this language's keys

      • iterator

        public java.util.Iterator<java.lang.String> iterator()
        Returns an iterator that iterates over the keys in this language (not including any parents).
        Specified by:
        iterator in interface java.lang.Iterable<java.lang.String>
        Returns:
        an iterator over this language's keys

      • getCollator

        public java.text.Collator getCollator()
        Returns a Collator that can be used to sort strings in this language.
        Returns:
        a Collator instance

      • getPluralizer

        public IntegerPluralizer getPluralizer()
        Returns a pluralizer for strings in the this language.
        Returns:
        a formatter for descriptions of integer quantities

      • getInterface

        public static Language getInterface()
        Returns the shared Language instance that represents the UI language.
        Returns:
        the UI language instance

      • getGame

        public static Language getGame()
        Returns the shared Language instance that represents the game language.
        Returns:
        the game language instance

      • setInterfaceLocale

        public static void setInterfaceLocale​(java.util.Locale ui)
        Sets the locale used for the shared interface language.
        Parameters:
        ui - the locale to use

      • getInterfaceLocale

        public static java.util.Locale getInterfaceLocale()
        Returns the user interface locale.
        Returns:
        the interface locale

      • setGameLocale

        public static void setGameLocale​(java.util.Locale game)
        Sets the locale used for the shared game language.
        Parameters:
        game - the locale to use

      • getGameLocale

        public static java.util.Locale getGameLocale()
        Returns the game locale.
        Returns:
        the game locale

      • string

        public static java.lang.String string​(java.lang.String key)
        Returns a string looked up with the default interface language. Cover for Language.getInterface().get( key ).
        Parameters:
        key - the key for the string to retrieve
        Returns:
        the localized string, or [MISSING: key]

      • string

        public static java.lang.String string​(java.lang.String key,
                                      java.lang.Object... args)
        Formats and returns a format string looked up with the default interface language. Formatting flags in the localized string will be filled in using the supplied args.
        Parameters:
        key - the key for the localized formatting template
        args - the arguments to use to fill in the formatting template
        Returns:
        the localized, formatted string or [MISSING: key]

      • gstring

        public static java.lang.String gstring​(java.lang.String key)
        Returns a string looked up with the default game language. Cover for Language.getInterface().get( key ).
        Parameters:
        key - the key for the string to retrieve
        Returns:
        the localized string, or [MISSING: key]

      • gstring

        public static java.lang.String gstring​(java.lang.String key,
                                       java.lang.Object... args)
        Formats and returns a format string looked up with the default game language. Formatting flags in the localized string will be filled in using the supplied args.
        Parameters:
        key - the key for the localized formatting template
        args - the arguments to use to fill in the formatting template
        Returns:
        the localized, formatted string or [MISSING: key]

      • parseLocaleDescription

        public static java.util.Locale parseLocaleDescription​(java.lang.String code)
        Parses a locale description in ll_CC format and returns the Locale.
        Parameters:
        code - a locale described with a two-letter language and optional two-letter country
        Returns:
        the parsed locale

      • isLocaleDescriptionValid

        public static boolean isLocaleDescriptionValid​(java.lang.String description)
        Returns true if a locale description represents a valid locale. In order to be valid, a locale description must have one of the following forms, where x indicates a lower case letter and X indicates an upper case letter:
        xx
        xx_XX
        Note that variants (further descriptions of the locale that may follow the country code after an additional underscore) are not supported by Strange Eons at this time.
        Returns:
        true if the locale description is syntactically valid

      • getInterfaceLocales

        public static java.util.Locale[] getInterfaceLocales()
        Returns a sorted array of the available interface locales.
        Returns:
        a non-empty array of supported locales

      • getGameLocales

        public static java.util.Locale[] getGameLocales()
        Returns a sorted array of the available game locales.
        Returns:
        a non-empty array of supported locales

      • getLocales

        public static java.util.Locale[] getLocales()
        Returns a sorted array of all available locales. This includes a large set of known standard locales along with any added interface and game locales not included in this known set.
        Returns:
        a non-empty array of supported locales

      • getResourceChain

        public java.lang.String[] getResourceChain​(java.lang.String baseName,
                                           java.lang.String suffix)
        Returns an array of resources that match the requested file name from least to most specialized for the locale's language. This is done by composing the following resource file names, in order:
        1. baseName + suffix
        2. baseName + "_" + locale.getLanguage() + suffix
        3. baseName + "_" + locale.getLanguage() + "_" + locale.getCountry() + suffix
        At each of these steps, if there is a resource available that matches the name, it will be added to the returned array. If not, then the search ends. (If the locale does not specify a country, step 3 will not be performed. If it does not specify a language, then neither step 2 nor step 3 will be performed.) Thus, this method returns an array of between 0 and 3 resource files. For example, the following line would return the main application interface text resources that match the interface locale:
        Language.getInterface().getResourceChain( "text/interface/eons-text", ".properties" )
        Parameters:
        baseName - the path and base file name of the resource
        suffix - the suffix to append to the end of the name; typically this is a file extension
        Returns:
        between 0 and 3 resource files that exist and match the locale

      • getIconForCountry

        public static javax.swing.Icon getIconForCountry​(java.util.Locale loc)
        Returns a flag icon for the country part of locale loc. If the locale has no country part, or if no flag is available for the country, a blank placeholder icon will be returned. The placeholder icon is the same size as the flag icon would have been, if one was available. In no event will null be returned.
        Parameters:
        loc - the locale to return a flag for
        Returns:
        a small flag icon for the country of the requested locale, or a blank icon
        Throws:
        java.lang.NullPointerException - if loc is null

      • getIconForLanguage

        public static javax.swing.Icon getIconForLanguage​(java.util.Locale loc)
        Returns an icon for the language part of locale loc. If the locale has no language part, or if no icon is available for the language, a blank placeholder icon will be returned. The placeholder icon is the same size as the language icon would have been, if one was available. In no event will null be returned.
        Parameters:
        loc - the locale to return a flag for
        Returns:
        a small icon for the language of the requested locale, or a blank icon
        Throws:
        java.lang.NullPointerException - if loc is null

      • getIconForLocale

        public static javax.swing.Icon getIconForLocale​(java.util.Locale loc)
        Returns an icon that represents the language and country of a locale. If a representation for the language or country is not available, that part of the resulting icon will be blank. In no event will null be returned.
        Parameters:
        loc - the locale to return a flag for
        Returns:
        a small icon for the requested locale, or a blank icon
        Throws:
        java.lang.NullPointerException - if loc is null

      • addInterfaceLocale

        public static void addInterfaceLocale​(java.util.Locale loc)
        Marks the locale loc as a "preferred locale" for interface language purposes. This method is not normally called directly. Instead, plug-in authors will place a ui-languages client property in their root file with a comma-separated list of all of the interface locales supported by the plug-in. The bundle installer will automatically mark these as preferred when it loads the bundle. Preferred locales are given priority when the user selects languages in the Preferences dialog.
        Parameters:
        loc - the locale to prioritize
        Throws:
        java.lang.NullPointerException - if loc is null
        java.lang.IllegalArgumentException - if there is no language defined in the locale or there is a variant defined

      • addGameLocale

        public static void addGameLocale​(java.util.Locale loc)
        Marks the locale loc as a "preferred locale" for game language purposes. This method is not normally called directly. Instead, plug-in authors will place a game-languages client property in their root file with a comma-separated list of all of the game locales supported by the plug-in. The bundle installer will automatically mark these as preferred when it loads the bundle. Preferred locales are given priority when the user selects languages in the Preferences dialog.

        Note: Adding a locale that includes a country automatically implies that the base locale with only a language and no country is also preferred.

        Parameters:
        loc - the locale to prioritize
        Throws:
        java.lang.NullPointerException - if loc is null
        java.lang.IllegalArgumentException - if there is no language defined in the locale or there is a variant defined

      • toString

        public java.lang.String toString()
        Returns the string representation of this language, a string describing the language's locale.
        Overrides:
        toString in class java.lang.Object
        Returns:
        the locale string for the language's locale