Package ca.cgjennings.i18n

Class IntegerPluralizer

  • public class IntegerPluralizer
extends java.lang.Object
    A pluralizer for integer quantities. A pluralizer is used to select the correct localized plural form for a given quantity. For example, in English one writes "1 orange" but "2 oranges"; "1 ox" but "2 oxen". Depending on the locale, a word may have one plural form or many. The pluralizer understands the pluralization rules for the various locales that it supports, and it can supply the correct form automatically so long as you set up your localization files in the way that it expects.

    Although you can request a pluralizer for any locale by calling create(java.util.Locale), you do not normally create a pluralizer yourself. Instead, you obtain a pluralizer from the appropriate Language. For example, to pluralize text in the user interface language, you would call Language.getInterface().getPluralizer() to get the pluralizer for the user interface language.

    The most common way to set up your .properties file when you want to add a pluralizable string is to add a key for the singular form, then add a separate key with "-pl" on the end for the plural. For example: 

     elephant-count = I see %d elephant.
 elephant-count-pl = I see %d elephants.

    For locales with more than one plural form, additional keys would be defined with the names elephant-count-pl2, elephant-count-pl3, and so on. Locales that don't have plural forms would simply define the singular form key.

    Using a Language instance that has this .properties file loaded, you could obtain a properly formatted and localized plural by calling code similar to the following: 

    language.getPluralizer().pluralize( numElephants, "elephant-count", numElephants );
    (The second numElephants argument is used to replace the %d in the plural string.)
    Author:
    Chris Jennings

    • Constructor Summary

      Constructors 
      Modifier Constructor Description
      protected IntegerPluralizer()
      Creates a new pluralizer instance.

    • Method Summary

      All Methods Static Methods Instance Methods Concrete Methods 
      Modifier and Type Method Description
      static IntegerPluralizer create()
      Create a pluralizer for the default locale.
      static IntegerPluralizer create​(java.util.Locale loc)
      Create a pluralizer for the requested locale.
      java.lang.String createKey​(int pluralForm, java.lang.String basePrefix, java.lang.String baseSuffix, java.lang.String singularInfix, java.lang.String pluralInfix)
      Returns a key name based on a plural form index and base key name parts.
      Language getLanguage()
      Returns the default language instance that will be used by this pluralizer to look up plural form strings.
      int getPluralForm​(int number)
      Returns the plural form index to use for number.
      int getPluralForm​(long number)
      Returns the plural form index to use for a number.
      int getPluralFormCount()
      Returns the number of plural forms used by this pluralizer.
      java.lang.String getPluralFormDescription()
      Returns a brief description, in English, of the rule used by the pluralizer to select a plural form.
      boolean isFallbackPluralizer()
      If this returns true, then there is no built-in pluralizer for this pluralizer's locale and a default pluralizer is being used that follows the same rules as English.
      java.lang.String pluralize​(int number, java.lang.String resourceKeyBase)
      Returns an appropriate plural form string based on an integer value.
      java.lang.String pluralize​(int number, java.lang.String resourceKeyBase, java.lang.Object... formatObjects)
      Returns a pluralized string that has been formatted using the supplied objects.
      java.lang.String pluralize​(Language language, int number, java.lang.String resourceKeyBase)
      Returns an appropriate plural form string based on an integer value.
      java.lang.String pluralize​(Language language, int number, java.lang.String resourceKeyBase, java.lang.Object... formatObjects)
      Returns a pluralized string that has been formatted using the supplied objects.
      void setLanguage​(Language language)
      Sets the language instance to use when looking up plural form strings.
      java.lang.String toString()  

      • Methods inherited from class java.lang.Object

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

    • Constructor Detail

      • IntegerPluralizer

        protected IntegerPluralizer()
        Creates a new pluralizer instance.

    • Method Detail

      • create

        public static IntegerPluralizer create()
        Create a pluralizer for the default locale. If no more specific pluralizer is available, a default pluralizer is returned that follows the same rules as English.
        Returns:
        a pluralizer for the default locale

      • create

        public static IntegerPluralizer create​(java.util.Locale loc)
        Create a pluralizer for the requested locale.

        The base class includes built-in support for a number of languages. If none of these is suitable, then it will attempt to instantiate a class in this package with the name IntegerPluralizer_<i>xx</i>, where xx is the language code for the locale. If this class cannot be found and instantiated, then a default pluralizer is returned that follows the same rules as English.

        Parameters:
        loc - the locale, or null to use the default locale
        Returns:
        a pluralizer for the locale

      • getPluralForm

        public int getPluralForm​(int number)
        Returns the plural form index to use for number. For example, the English pluralizer returns plural form 0 (singular) if number == 1, and otherwise returns 1 (first plural form).

        Subclasses that implement support for specific locales must override this method.

        Parameters:
        number - the number to choose a plural form for
        Returns:
        the plural form index for the chosen number in this pluralizer's locale
        See Also:
        createKey(int, java.lang.String, java.lang.String, java.lang.String, java.lang.String)

      • getPluralFormCount

        public int getPluralFormCount()
        Returns the number of plural forms used by this pluralizer. For example, an English pluralizer would return 2, a Japanese pluralizer would return 1 (since Japanese doesn't use different word forms based on quantity), and a Polish pluralizer would return 3.
        Returns:
        the number of plural forms used by this pluralizer; this is one more than the maximum value that may be returned by getPluralForm(int).

      • getPluralFormDescription

        public java.lang.String getPluralFormDescription()
        Returns a brief description, in English, of the rule used by the pluralizer to select a plural form. Although the description is in English, it follows a specific format so that it can be readily parsed to format it for display. Each plural form is described on a separate line, in increasing order, and each line is divided by a colon. Before the colon comes a description of when the form applies, and after the colon comes an example key name for a key with the base name "key". For example: 
         N is 1: key
 N ends in 2-4, except if it ends in 12-14: key-pl
 Everything else: key-pl2
        Returns:
        a brief description of the pluralization rule

      • createKey

        public java.lang.String createKey​(int pluralForm,
                                  java.lang.String basePrefix,
                                  java.lang.String baseSuffix,
                                  java.lang.String singularInfix,
                                  java.lang.String pluralInfix)
        Returns a key name based on a plural form index and base key name parts. The value of pluralForm is 0 for the singular form, 1 for the first plural form, 2 for the second plural form, and so on. (The exact meaning of the plural form index is locale-dependent.) The returned key name is composed by following this pattern: 
         basePrefix + singularInfix     + baseSuffix      (plural form 0)
 basePrefix + pluralInfix       + baseSuffix      (plural form 1)
 basePrefix + pluralInfix + "2" + baseSuffix      (plural form 2)
 basePrefix + pluralInfix + "3" + baseSuffix      (plural form 3)
 ...
        Parameters:
        basePrefix - the prefix used for all keys (may be empty)
        baseSuffix - the suffix used for all keys (may be empty)
        singularInfix - the infix used if the plural index is for the singular form
        pluralInfix - the infix used for the first plural form, and as the basis of subsequent plural forms
        Returns:
        a key composed for the specific plural form

      • pluralize

        public java.lang.String pluralize​(int number,
                                  java.lang.String resourceKeyBase)
        Returns an appropriate plural form string based on an integer value. This is a convenience method that is equivalent to pluralize( getLanguage(), number, resourceKeyBase ).
        Parameters:
        number - the number to for which a plural form should be selected
        resourceKeyBase - the base key to use to generate a key set
        Returns:
        the appropriate plural form, or an error message
        See Also:
        pluralize(resources.Language, int, java.lang.String)

      • pluralize

        public java.lang.String pluralize​(Language language,
                                  int number,
                                  java.lang.String resourceKeyBase)
        Returns an appropriate plural form string based on an integer value. A set of keys is generated as if by calling createKeys( resourceKeyBase, "", "", "-pl" ). This means that the following keys will be used:
        <i>resourceKeyBase</i> singular form
        <i>resourceKeyBase</i>-pl first plural form
        <i>resourceKeyBase</i>-pl2 second plural form
        ...

        Of these keys, the appropriate key will be selected based on the value of number, and then the value of this key in language returned.

        Parameters:
        language - the language to use to look up the plural string
        number - the number to for which a plural form should be selected
        resourceKeyBase - the base key to use to generate a key set
        Returns:
        the appropriate plural form, or an error message
        Throws:
        java.lang.NullPointerException - if the language or base key is null

      • pluralize

        public java.lang.String pluralize​(int number,
                                  java.lang.String resourceKeyBase,
                                  java.lang.Object... formatObjects)
        Returns a pluralized string that has been formatted using the supplied objects. This is a convenience for calling String.format on the result of a call to pluralize(int, java.lang.String).
        Parameters:
        number - the number to for which a plural form should be selected
        resourceKeyBase - the base key to use to generate a key set
        formatObjects - the objects to use when formatting the resulting string
        Returns:
        a localized, pluralized, and formatted string
        Throws:
        java.lang.NullPointerException - if the base key is null

      • pluralize

        public java.lang.String pluralize​(Language language,
                                  int number,
                                  java.lang.String resourceKeyBase,
                                  java.lang.Object... formatObjects)
        Returns a pluralized string that has been formatted using the supplied objects. This is a convenience for calling String.format on the result of a call to pluralize(resources.Language, int, java.lang.String).
        Parameters:
        language - the language to use to look up the plural string
        number - the number to for which a plural form should be selected
        resourceKeyBase - the base key to use to generate a key set
        formatObjects - the objects to use when formatting the resulting string
        Returns:
        a localized, pluralized, and formatted string
        Throws:
        java.lang.NullPointerException - if the language or base key is null

      • getLanguage

        public Language getLanguage()
        Returns the default language instance that will be used by this pluralizer to look up plural form strings.
        Returns:
        the default language that this pluralizer will use to look up pluralized strings

      • setLanguage

        public void setLanguage​(Language language)
        Sets the language instance to use when looking up plural form strings. (The default for new pluralizer instances is Language.getInterface().)
        Parameters:
        language - the new default language for this instance
        Throws:
        java.lang.NullPointerException - if the language is null

      • toString

        public java.lang.String toString()
        Overrides:
        toString in class java.lang.Object

      • isFallbackPluralizer

        public final boolean isFallbackPluralizer()
        If this returns true, then there is no built-in pluralizer for this pluralizer's locale and a default pluralizer is being used that follows the same rules as English. When starting a translation, you can test if pluralizer support needs to be added by running script code similar to the following (where ll is the relevant language code): 
        println( ca.cgjennings.i18n.IntegerPluralizer.create( new java.util.Locale("ll") ).isFallbackPluralizer() );
        If this prints true, then you should request that pluralization support be added for your language. Alternatively, if you are familiar with Java, you can add support yourself by writing a class with the name IntegerPluralizer_<i>ll</i>. The class must be in the same package as this class, and it must subclass IntegerPluralizer and override the getPluralForm(int), getPluralFormCount(), and getPluralFormDescription() methods to implement the pluralization rule for the locale.
        Returns:
        true if pluralizer support for your locale needs to be added