Package com.day.cq.i18n

Class I18n

  • public class I18n
extends java.lang.Object
    Externalizes strings using ResourceBundle dictionaries and simulatenously acts as marker for the string extraction process. In addition to plain string translation, it allows for translation comments and placeholders ({0}, {1}, etc.). ResourceBundles will be taken from a SlingHttpServletRequest and it's default locale (standard case) or can be passed explicitly.

    There are two kinds of methods, which are identical in their implementation, but have a different signature to indicate the proper intention to the string extraction tool:

    • get(): for use with literal strings, also acts as marker for the string extraction

      Example: i18n.get("Label");

      Note that this below is incorrect - while it works programmatically, it prevents the string from being extracted if the literal is not part of the method call directly:

      String title = "Label"; i18n.get(title);

    • getVar(): for use with string variables where the actual string is read and extracted from another location (e.g. the JCR)

      Example: String var = properties.get("jcr:title", String.class); i18n.getVar(var);

      When using this method, make sure the string gets extracted properly from the other location (i18n engineers will know).

    There are basically three ways to use this class:

    1. static, using HttpServletRequest as source (will use the default language and resource bundle from the request object, ie. using slingRequest.getResourceBundle(null))
    2. static, using a ResourceBundle as source
    3. as object instance, created from a HttpServletRequest (like 1, but shorter calls): 
       I18n i18n = new I18n(slingRequest);
    4. as object instance, created from a ResourceBundle (like 2, but shorter calls): 
       I18n i18n = new I18n(resourceBundle);

    • Constructor Summary

      Constructors 
      Constructor Description
      I18n​(java.util.ResourceBundle resourceBundle)  
      I18n​(HttpServletRequest request)  

    • Method Summary

      All Methods Static Methods Instance Methods Concrete Methods 
      Modifier and Type Method Description
      java.lang.String get​(java.lang.String text)
      Translates the given text.
      java.lang.String get​(java.lang.String text, java.lang.String comment)
      Translates the given text considering a special comment for translators.
      java.lang.String get​(java.lang.String text, java.lang.String comment, java.lang.Object... args)
      Translates the given text considering a special comment for translators and replaces placeholders ({0}, {1}, etc.) with the given arguments.
      static java.lang.String get​(java.util.ResourceBundle resourceBundle, java.lang.String text)
      Translates the given text.
      static java.lang.String get​(java.util.ResourceBundle resourceBundle, java.lang.String text, java.lang.String comment)
      Translates the given text considering a special comment for translators.
      static java.lang.String get​(java.util.ResourceBundle resourceBundle, java.lang.String text, java.lang.String comment, java.lang.Object... args)
      Translates the given text considering a special comment for translators and replaces placeholders ({0}, {1}, etc.) with the given arguments.
      static java.lang.String get​(HttpServletRequest request, java.lang.String text)
      Translates the given text.
      static java.lang.String get​(HttpServletRequest request, java.lang.String text, java.lang.String comment)
      Translates the given text considering a special comment for translators.
      static java.lang.String get​(HttpServletRequest request, java.lang.String text, java.lang.String comment, java.lang.Object... args)
      Translates the given text considering a special comment for translators and replaces placeholders ({0}, {1}, etc.) with the given arguments.
      java.lang.String getVar​(java.lang.String text)
      Translates the given text.
      java.lang.String getVar​(java.lang.String text, java.lang.String comment)
      Note: this variant is only for rare cases.
      java.lang.String getVar​(java.lang.String text, java.lang.String comment, java.lang.Object... args)
      Translates the given text considering a special comment for translators and replaces placeholders ({0}, {1}, etc.) with the given arguments.
      static java.lang.String getVar​(java.util.ResourceBundle resourceBundle, java.lang.String text)
      Translates the specified text into the current language.
      static java.lang.String getVar​(java.util.ResourceBundle resourceBundle, java.lang.String text, java.lang.String comment)
      Note: this variant is only for rare cases.
      static java.lang.String getVar​(java.util.ResourceBundle resourceBundle, java.lang.String text, java.lang.String comment, java.lang.Object... args)
      Translates the given text considering a special comment for translators and replaces placeholders ({0}, {1}, etc.) with the given arguments.
      static java.lang.String getVar​(HttpServletRequest request, java.lang.String text)
      Translates the specified text into the current language.
      static java.lang.String getVar​(HttpServletRequest request, java.lang.String text, java.lang.String comment)
      Note: this variant is only for rare cases.
      static java.lang.String getVar​(HttpServletRequest request, java.lang.String text, java.lang.String comment, java.lang.Object... args)
      Translates the given text considering a special comment for translators and replaces placeholders ({0}, {1}, etc.) with the given arguments.

      • Methods inherited from class java.lang.Object

        equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

    • Constructor Detail

      • I18n

        public I18n​(java.util.ResourceBundle resourceBundle)

    • Method Detail

      • get

        public java.lang.String get​(java.lang.String text)
        Translates the given text. Will return the original text if no translation was found.

        If this object was created via I18n(HttpServletRequest), the default language resource bundle of the sling request will be used, otherwise it uses the underlying ResourceBundle provided in I18n(ResourceBundle).

        Parameters:
        text - The text to translate - as string literal "My Label"
        Returns:
        the translation, or the original text if no translation was found

      • get

        public java.lang.String get​(java.lang.String text,
                            java.lang.String comment)
        Translates the given text considering a special comment for translators. Will return the original text if no translation was found.

        If this object was created via I18n(HttpServletRequest), the default language resource bundle of the sling request will be used, otherwise it uses the underlying ResourceBundle provided in I18n(ResourceBundle).

        Parameters:
        text - The text to translate - as string literal "My Label"
        comment - A comment for translators to specify the context in which the text is used - as string literal "Action button label"
        Returns:
        the translation, or the original text if no translation was found

      • get

        public java.lang.String get​(java.lang.String text,
                            java.lang.String comment,
                            java.lang.Object... args)
        Translates the given text considering a special comment for translators and replaces placeholders ({0}, {1}, etc.) with the given arguments. Will return the original text if no translation was found.

        If this object was created via I18n(HttpServletRequest), the default language resource bundle of the sling request will be used, otherwise it uses the underlying ResourceBundle provided in I18n(ResourceBundle).

        Parameters:
        text - The text to translate - as string literal "My Label"
        comment - A comment for translators to specify the context in which the text is used - as string literal "Action button label" (can be null).
        args - A varargs list that (as Strings) will be used to replace numbered placeholders in the text (eg. ({0}, {1}, etc.)
        Returns:
        the translation, or the original text if no translation was found

      • getVar

        public java.lang.String getVar​(java.lang.String text)
        Translates the given text. Will return the original text if no translation was found.

        Use this variant to translate string variables which have a value read from somewhere else, such as the JCR repository. In this case the getVar() signature marks it clearly that the extraction tool should not expect a literal string here. When adding this, make sure the string gets extracted properly from the JCR repository for example (i18n engineers will know).

        If this object was created via I18n(HttpServletRequest), the default language resource bundle of the sling request will be used, otherwise it uses the underlying ResourceBundle provided in I18n(ResourceBundle).

        Parameters:
        text - The text to translate
        Returns:
        the translation, or the original text if no translation was found

      • getVar

        public java.lang.String getVar​(java.lang.String text,
                               java.lang.String comment)
        Note: this variant is only for rare cases.

        Translates the given text considering a special comment for translators. Will return the original text if no translation was found.

        Use this variant to translate string variables which have a value read from somewhere else, such as the JCR repository. In this case the getVar() signature marks it clearly that the extraction tool should not expect a literal string here. When adding this, make sure the string gets extracted properly from the JCR repository for example (i18n engineers will know).

        Warning: It is very important that the translation comment passed as second argument is present in the dictionary (unless it's null). Since in the getVar() case the strings are read or extracted from a different location, this comment must also be present wherever the strings are extracted from, and read from there! Because of this, there will usually be no comment with getVar() (null).

        If this object was created via I18n(HttpServletRequest), the default language resource bundle of the sling request will be used, otherwise it uses the underlying ResourceBundle provided in I18n(ResourceBundle).

        Parameters:
        text - The text to translate
        comment - A comment for translators to specify the context in which the text is used (can be null). Warning: must also be present in the exact same form where the actual string is read from, which is usually impractical, so by default skip with null.
        Returns:
        the translation, or the original text if no translation was found

      • getVar

        public java.lang.String getVar​(java.lang.String text,
                               java.lang.String comment,
                               java.lang.Object... args)
        Translates the given text considering a special comment for translators and replaces placeholders ({0}, {1}, etc.) with the given arguments. Will return the original text if no translation was found.

        Use this variant to translate string variables which have a value read from somewhere else, such as the JCR repository. In this case the getVar() signature marks it clearly that the extraction tool should not expect a literal string here. When adding this, make sure the string gets extracted properly from the JCR repository for example (i18n engineers will know).

        Warning: It is very important that the translation comment passed as second argument is present in the dictionary (unless it's null). Since in the getVar() case the strings are read or extracted from a different location, this comment must also be present wherever the strings are extracted from, and read from there! Because of this, there will usually be no comment with getVar() (null): 

        i18n.getVar(text, null, variable1, variable2);

        If this object was created via I18n(HttpServletRequest), the default language resource bundle of the sling request will be used, otherwise it uses the underlying ResourceBundle provided in I18n(ResourceBundle).

        Parameters:
        text - The text to translate
        comment - A comment for translators to specify the context in which the text is used (can be null). Warning: must also be present in the exact same form where the actual string is read from, which is usually impractical, so by default skip with null.
        args - A varargs list that (as Strings) will be used to replace numbered placeholders in the text (eg. ({0}, {1}, etc.)
        Returns:
        the translation, or the original text if no translation was found

      • get

        public static java.lang.String get​(HttpServletRequest request,
                                   java.lang.String text)
        Translates the given text. Will return the original text if no translation was found.

        Uses the default language resource bundle of the sling request, ie. using slingRequest.getResourceBundle(null).

        Parameters:
        request - The request object of which the default language resource bundle will be taken from as translation source
        text - The text to translate - as string literal "My Label"
        Returns:
        the translation, or the original text if no translation was found

      • get

        public static java.lang.String get​(HttpServletRequest request,
                                   java.lang.String text,
                                   java.lang.String comment)
        Translates the given text considering a special comment for translators. Will return the original text if no translation was found.

        Uses the default language resource bundle of the sling request, ie. using slingRequest.getResourceBundle(null).

        Parameters:
        request - The request object of which the default language resource bundle will be taken from as translation source
        text - The text to translate - as string literal "My Label"
        comment - A comment for translators to specify the context in which the text is used - as string literal "Action button label"
        Returns:
        the translation, or the original text if no translation was found

      • get

        public static java.lang.String get​(HttpServletRequest request,
                                   java.lang.String text,
                                   java.lang.String comment,
                                   java.lang.Object... args)
        Translates the given text considering a special comment for translators and replaces placeholders ({0}, {1}, etc.) with the given arguments. Will return the original text if no translation was found.

        Uses the default language resource bundle of the sling request, ie. using slingRequest.getResourceBundle(null).

        Parameters:
        request - The request object of which the default language resource bundle will be taken from as translation source
        text - The text to translate - as string literal "My Label"
        comment - A comment for translators to specify the context in which the text is used - as string literal "Action button label" (can be null).
        args - A varargs list that (as Strings) will be used to replace numbered placeholders in the text (eg. ({0}, {1}, etc.)
        Returns:
        the translation, or the original text if no translation was found

      • getVar

        public static java.lang.String getVar​(HttpServletRequest request,
                                      java.lang.String text)
        Translates the specified text into the current language.

        Use this variant to translate string variables which have a value read from somewhere else, such as the JCR repository. In this case the getVar() signature marks it clearly that the extraction tool should not expect a literal string here. When adding this, make sure the string gets extracted properly from the JCR repository for example (i18n engineers will know).

        Uses the default language resource bundle of the sling request, ie. using slingRequest.getResourceBundle(null).

        Parameters:
        request - The request object of which the default language resource bundle will be taken from as translation source
        text - The text to translate
        Returns:
        the translation of the specified text into the current language

      • getVar

        public static java.lang.String getVar​(HttpServletRequest request,
                                      java.lang.String text,
                                      java.lang.String comment)
        Note: this variant is only for rare cases.

        Translates the specified text considering a special comment for translators into the current language.

        Use this variant to translate string variables which have a value read from somewhere else, such as the JCR repository. In this case the getVar() signature marks it clearly that the extraction tool should not expect a literal string here. When adding this, make sure the string gets extracted properly from the JCR repository for example (i18n engineers will know).

        Warning: It is very important that the translation comment passed as second argument is present in the dictionary (unless it's null). Since in the getVar() case the strings are read or extracted from a different location, this comment must also be present wherever the strings are extracted from, and read from there! Because of this, there will usually be no comment with getVar() (null).

        Uses the default language resource bundle of the sling request, ie. using slingRequest.getResourceBundle(null).

        Parameters:
        request - The request object of which the default language resource bundle will be taken from as translation source
        text - The text to translate
        comment - A comment for translators to specify the context in which the text is used (can be null). Warning: must also be present in the exact same form where the actual string is read from, which is usually impractical, so by default skip with null.
        Returns:
        the translation of the specified text into the current language

      • getVar

        public static java.lang.String getVar​(HttpServletRequest request,
                                      java.lang.String text,
                                      java.lang.String comment,
                                      java.lang.Object... args)
        Translates the given text considering a special comment for translators and replaces placeholders ({0}, {1}, etc.) with the given arguments. Will return the original text if no translation was found.

        Use this variant to translate string variables which have a value read from somewhere else, such as the JCR repository. In this case the getVar() signature marks it clearly that the extraction tool should not expect a literal string here. When adding this, make sure the string gets extracted properly from the JCR repository for example (i18n engineers will know).

        Warning: It is very important that the translation comment passed as second argument is present in the dictionary (unless it's null). Since in the getVar() case the strings are read or extracted from a different location, this comment must also be present wherever the strings are extracted from, and read from there! Because of this, there will usually be no comment with getVar() (null): 

        I18n.getVar(request, text, null, variable1, variable2);

        Uses the default language resource bundle of the sling request, ie. using slingRequest.getResourceBundle(null).

        Parameters:
        request - The request object of which the default language resource bundle will be taken from as translation source
        text - The text to translate
        comment - A comment for translators to specify the context in which the text is used (can be null). Warning: must also be present in the exact same form where the actual string is read from, which is usually impractical, so by default skip with null.
        args - A varargs list that (as Strings) will be used to replace numbered placeholders in the text (eg. ({0}, {1}, etc.)
        Returns:
        the translation, or the original text if no translation was found

      • get

        public static java.lang.String get​(java.util.ResourceBundle resourceBundle,
                                   java.lang.String text)
        Translates the given text. Will return the original text if no translation was found.

        Uses the given ResourceBundle as translation source.

        Parameters:
        resourceBundle - The resourceBundle used as translation source
        text - The text to translate - as string literal "My Label"
        Returns:
        the translation, or the original text if no translation was found

      • get

        public static java.lang.String get​(java.util.ResourceBundle resourceBundle,
                                   java.lang.String text,
                                   java.lang.String comment)
        Translates the given text considering a special comment for translators. Will return the original text if no translation was found.

        Uses the given ResourceBundle as translation source.

        Parameters:
        resourceBundle - The resourceBundle used as translation source
        text - The text to translate - as string literal "My Label"
        comment - A comment for translators to specify the context in which the text is used - as string literal "Action button label"
        Returns:
        the translation, or the original text if no translation was found

      • get

        public static java.lang.String get​(java.util.ResourceBundle resourceBundle,
                                   java.lang.String text,
                                   java.lang.String comment,
                                   java.lang.Object... args)
        Translates the given text considering a special comment for translators and replaces placeholders ({0}, {1}, etc.) with the given arguments. Will return the original text if no translation was found.

        Uses the given ResourceBundle as translation source.

        Parameters:
        resourceBundle - The resourceBundle used as translation source
        text - The text to translate - as string literal "My Label"
        comment - A comment for translators to specify the context in which the text is used - as string literal "Action button label" (can be null).
        args - A varargs list that (as Strings) will be used to replace numbered placeholders in the text (eg. ({0}, {1}, etc.)
        Returns:
        the translation, or the original text if no translation was found

      • getVar

        public static java.lang.String getVar​(java.util.ResourceBundle resourceBundle,
                                      java.lang.String text)
        Translates the specified text into the current language.

        Use this variant to translate string variables which have a value read from somewhere else, such as the JCR repository. In this case the getVar() signature marks it clearly that the extraction tool should not expect a literal string here. When adding this, make sure the string gets extracted properly from the JCR repository for example (i18n engineers will know).

        Uses the given ResourceBundle as translation source.

        Parameters:
        resourceBundle - The resourceBundle used as translation source
        text - The text to translate
        Returns:
        the translation of the specified text into the current language

      • getVar

        public static java.lang.String getVar​(java.util.ResourceBundle resourceBundle,
                                      java.lang.String text,
                                      java.lang.String comment)
        Note: this variant is only for rare cases.

        Translates the specified text considering a special comment for translators into the current language.

        Use this variant to translate string variables which have a value read from somewhere else, such as the JCR repository. In this case the getVar() signature marks it clearly that the extraction tool should not expect a literal string here. When adding this, make sure the string gets extracted properly from the JCR repository for example (i18n engineers will know).

        Warning: It is very important that the translation comment passed as second argument is present in the dictionary (unless it's null). Since in the getVar() case the strings are read or extracted from a different location, this comment must also be present wherever the strings are extracted from, and read from there! Because of this, there will usually be no comment with getVar() (null).

        Uses the given ResourceBundle as translation source.

        Parameters:
        resourceBundle - The resourceBundle used as translation source
        text - The text to translate
        comment - A comment for translators to specify the context in which the text is used (can be null). Warning: must also be present in the exact same form where the actual string is read from, which is usually impractical, so by default skip with null.
        Returns:
        the translation of the specified text into the current language

      • getVar

        public static java.lang.String getVar​(java.util.ResourceBundle resourceBundle,
                                      java.lang.String text,
                                      java.lang.String comment,
                                      java.lang.Object... args)
        Translates the given text considering a special comment for translators and replaces placeholders ({0}, {1}, etc.) with the given arguments. Will return the original text if no translation was found.

        Use this variant to translate string variables which have a value read from somewhere else, such as the JCR repository. In this case the getVar() signature marks it clearly that the extraction tool should not expect a literal string here. When adding this, make sure the string gets extracted properly from the JCR repository for example (i18n engineers will know).

        Warning: It is very important that the translation comment passed as second argument is present in the dictionary (unless it's null). Since in the getVar() case the strings are read or extracted from a different location, this comment must also be present wherever the strings are extracted from, and read from there! Because of this, there will usually be no comment with getVar() (null): 

        I18n.getVar(bundle, text, null, variable1, variable2);

        Uses the given ResourceBundle as translation source.

        Parameters:
        resourceBundle - The resourceBundle used as translation source
        text - The text to translate
        comment - A comment for translators to specify the context in which the text is used (can be null). Warning: must also be present in the exact same form where the actual string is read from, which is usually impractical, so by default skip with null.
        args - A varargs list that (as Strings) will be used to replace numbered placeholders in the text (eg. ({0}, {1}, etc.)
        Returns:
        the translation, or the original text if no translation was found