com.day.cq.i18n

Class I18n

java.lang.Object

com.day.cq.i18n.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 and Description
I18n(HttpServletRequest request)

Method Summary

Modifier and Type	Method and Description
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	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	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.
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.

Methods inherited from class java.lang.Object

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

Constructor Detail

I18n

public I18n(HttpServletRequest request)

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