Class I18n
- java.lang.Object
-
- com.day.cq.i18n.I18n
-
public class I18n extends Object
Externalizes strings usingResourceBundle
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 aSlingHttpServletRequest
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 extractionExample:
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:
- static, using
HttpServletRequest
as source (will use the default language and resource bundle from the request object, ie. usingslingRequest.getResourceBundle(null)
) - static, using a
ResourceBundle
as source - as object instance, created from a
HttpServletRequest
(like 1, but shorter calls):I18n i18n = new I18n(slingRequest);
- as object instance, created from a
ResourceBundle
(like 2, but shorter calls):I18n i18n = new I18n(resourceBundle);
-
-
-
Constructor Summary
Constructors Constructor Description I18n(ResourceBundle resourceBundle)
I18n(HttpServletRequest request)
-
Method Summary
All Methods Static Methods Instance Methods Concrete Methods Modifier and Type Method Description String
get(String text)
Translates the given text.String
get(String text, String comment)
Translates the given text considering a special comment for translators.String
get(String text, String comment, Object... args)
Translates the given text considering a special comment for translators and replaces placeholders ({0}
,{1}
, etc.) with the given arguments.static String
get(ResourceBundle resourceBundle, String text)
Translates the given text.static String
get(ResourceBundle resourceBundle, String text, String comment)
Translates the given text considering a special comment for translators.static String
get(ResourceBundle resourceBundle, String text, String comment, Object... args)
Translates the given text considering a special comment for translators and replaces placeholders ({0}
,{1}
, etc.) with the given arguments.static String
get(HttpServletRequest request, String text)
Translates the given text.static String
get(HttpServletRequest request, String text, String comment)
Translates the given text considering a special comment for translators.static String
get(HttpServletRequest request, String text, String comment, Object... args)
Translates the given text considering a special comment for translators and replaces placeholders ({0}
,{1}
, etc.) with the given arguments.String
getVar(String text)
Translates the given text.String
getVar(String text, String comment)
Note: this variant is only for rare cases.String
getVar(String text, String comment, Object... args)
Translates the given text considering a special comment for translators and replaces placeholders ({0}
,{1}
, etc.) with the given arguments.static String
getVar(ResourceBundle resourceBundle, String text)
Translates the specified text into the current language.static String
getVar(ResourceBundle resourceBundle, String text, String comment)
Note: this variant is only for rare cases.static String
getVar(ResourceBundle resourceBundle, String text, String comment, Object... args)
Translates the given text considering a special comment for translators and replaces placeholders ({0}
,{1}
, etc.) with the given arguments.static String
getVar(HttpServletRequest request, String text)
Translates the specified text into the current language.static String
getVar(HttpServletRequest request, String text, String comment)
Note: this variant is only for rare cases.static String
getVar(HttpServletRequest request, String text, String comment, Object... args)
Translates the given text considering a special comment for translators and replaces placeholders ({0}
,{1}
, etc.) with the given arguments.
-
-
-
Constructor Detail
-
I18n
public I18n(HttpServletRequest request)
-
I18n
public I18n(ResourceBundle resourceBundle)
-
-
Method Detail
-
get
public String get(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 underlyingResourceBundle
provided inI18n(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 String get(String text, 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 underlyingResourceBundle
provided inI18n(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 String get(String text, String comment, 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 underlyingResourceBundle
provided inI18n(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 benull
).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 String getVar(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 underlyingResourceBundle
provided inI18n(ResourceBundle)
.- Parameters:
text
- The text to translate- Returns:
- the translation, or the original text if no translation was found
-
getVar
public String getVar(String text, 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 thegetVar()
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 underlyingResourceBundle
provided inI18n(ResourceBundle)
.- Parameters:
text
- The text to translatecomment
- A comment for translators to specify the context in which the text is used (can benull
). 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 withnull
.- Returns:
- the translation, or the original text if no translation was found
-
getVar
public String getVar(String text, String comment, 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 thegetVar()
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 underlyingResourceBundle
provided inI18n(ResourceBundle)
.- Parameters:
text
- The text to translatecomment
- A comment for translators to specify the context in which the text is used (can benull
). 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 withnull
.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 String get(HttpServletRequest request, 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 sourcetext
- The text to translate - as string literal"My Label"
- Returns:
- the translation, or the original text if no translation was found
-
get
public static String get(HttpServletRequest request, String text, 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 sourcetext
- 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 String get(HttpServletRequest request, String text, String comment, 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 sourcetext
- 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 benull
).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 String getVar(HttpServletRequest request, 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 sourcetext
- The text to translate- Returns:
- the translation of the specified text into the current language
-
getVar
public static String getVar(HttpServletRequest request, String text, 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 thegetVar()
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 sourcetext
- The text to translatecomment
- A comment for translators to specify the context in which the text is used (can benull
). 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 withnull
.- Returns:
- the translation of the specified text into the current language
-
getVar
public static String getVar(HttpServletRequest request, String text, String comment, 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 thegetVar()
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 sourcetext
- The text to translatecomment
- A comment for translators to specify the context in which the text is used (can benull
). 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 withnull
.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 String get(ResourceBundle resourceBundle, 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 sourcetext
- The text to translate - as string literal"My Label"
- Returns:
- the translation, or the original text if no translation was found
-
get
public static String get(ResourceBundle resourceBundle, String text, 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 sourcetext
- 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 String get(ResourceBundle resourceBundle, String text, String comment, 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 sourcetext
- 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 benull
).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 String getVar(ResourceBundle resourceBundle, 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 sourcetext
- The text to translate- Returns:
- the translation of the specified text into the current language
-
getVar
public static String getVar(ResourceBundle resourceBundle, String text, 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 thegetVar()
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 sourcetext
- The text to translatecomment
- A comment for translators to specify the context in which the text is used (can benull
). 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 withnull
.- Returns:
- the translation of the specified text into the current language
-
getVar
public static String getVar(ResourceBundle resourceBundle, String text, String comment, 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 thegetVar()
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 sourcetext
- The text to translatecomment
- A comment for translators to specify the context in which the text is used (can benull
). 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 withnull
.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
-
-