Members
(static) preferredLanguage :string
The user's preferred language based on browser settings. If none of the user's languages is supported, the first supported language is used as the preferred language.
Type:
- string
(static, nullable) referenceLanguage :string
The reference language for direct text translations. This can be set either in
the HTML element's lang attribute or with
setConfiguration.
The reference language is used when translating by reference text instead of
by message id. This is done in the translate
method and also in the automatic translation of HTML "string" elements. If no
reference language is defined, all reference text is treated as a message id.
Type:
- string
(static, non-null) supportedLanguages :Array.<string>
List of supported languages. This must be set with setConfiguration.
Type:
- Array.<string>
lang :string
The language of this locale bundle.
Type:
- string
Methods
(static) setBundle(langnullable) → (non-null) {jrt.LocaleBundle}
Loads the translation bundle for the specified language. If lang is empty or
null, or if it's not supported, then preferredLanguage
is used.
This method translates the text content in HTML "string" elements. This elements are:
- Elements with the
translateattribute set to "yes". Selements, when their only content is text (make sure to remove the CSS line-through style if you use these).- The folloging elements, when their only content is text:
H1toH6,SUMMARY,TDin aTHEAD,TH,A,BUTTON,LABELandOPTION. If text in any of this elements should not be translated, set theirtranslateattribute to "no" (either directly or in some ancestor element). INPUTandTEXTAREAelements with aplaceholderattribute (only this is translated).- Elements with the
data-msgidattribute.
Elements with a data-msgid attribute are translated using that message id. If the
corresponding message string is an array and the element is UL or OL,
then the element is filled with LI elements (one per string in the array).
Otherwise, it is filled with P elements.
Elements without a data-msgid attribute are translated using the element's text
content (or placeholder value) as reference text.
This method also sets the href attribute of localized links, that is,
links which have one data-href-lang attribute defined for every supported
language lang. If the URL for the current locale language is not found, the URL
from href is used, if defined.
This method will also fill any "include elements" which are found (replacing their
previous contents). Include elements specify a document fragment to be included using the
data-docid attribute. Each document fragment must be defined in a subdirectory
within the translation domain directory. The name of a document subdirectory must be
the document id, and the name of the documents within must be docid.lang.html.
Parameters for the included document can be specified with data-name
attributes. The specified value will be inserted in elements that have a matching
data-name attribute. If the element receiving the value is IMG
or A, then the value is used as the element's src or href
attribute value. If the element is INPUT, it is replaced with the value.
In any other case, the element's contents are replaced with the value.
Parameters:
| Name | Type | Attributes | Description |
|---|---|---|---|
lang |
string |
<nullable> |
Returns:
Returns the loaded message bundle instance. You can always
get the currently loaded locale bundle with jrt.App#getLocale.
- Type
- jrt.LocaleBundle
(static) setConfiguration(supportedLanguagesopt, nullable, referenceLanguageopt, domainsopt, non-null)
This method should be used to set the locale bundles configuration, before calling
setBundle (otherwise, it will be called implicitly
with no parameters).
If the list of supported languages is not specified, then only the reference language will be supported.
If a reference language is not specified, then the reference language is assumed
to be the document's declared language (the HTML element's lang
attribute value).
Translations must be defined in the /locale directory with a set of JSON
translation files, one for each supported language, which must be named strings.lang.js.
Each translation file must contain an array of [key, translation]
pairs, where the key can be either a message id or a reference text and the value
is the translated text.
The set of translation files found in /locale is the default translation
domain. Alternatively, you can define different translation domains in subdirectories
of /locale. When doing so, the domains parameter must specify
the list of domains to load when loading a translation bundle for the app.
Parameters:
| Name | Type | Attributes | Description |
|---|---|---|---|
supportedLanguages |
Array.<string> |
<optional> <nullable> |
List of supported languages. |
referenceLanguage |
string |
<optional> |
The reference language. |
domains |
Array.<string> |
<optional> |
The language domains to use (the default domain if not specified). |
getString(msgid, substitution, singularMsgidopt) → {string}
Returns the translation for the specified message id in the currently loaded language, or "" if it's not defined (a warning is logged in the console in this case).
To get the translation for a reference text, use the translate
method instead.
Parameters:
| Name | Type | Attributes | Description |
|---|---|---|---|
msgid |
string | ||
substitution |
number | string | !Array.<string> | null | One or more substitution values (optional). |
|
singularMsgid |
string |
<optional> |
The message to translate instead of 'msgid' when 'substitution' equals 1. |
Throws:
-
If the specified msgid correspond to a text array.
- Type
- jrt.JrtError
Returns:
- Type
- string
getStringArray(msgid) → (nullable) {Array.<string>}
This method must be used instead of getString
when the message to be translated is an array of strings. Substitutions are not
supported in this case.
Parameters:
| Name | Type | Description |
|---|---|---|
msgid |
string | The id of the message to get. |
Throws:
-
If the specified msgid does not correspond to a text array.
- Type
- jrt.JrtError
Returns:
The corresponding message array or null if the id is not defined.
- Type
- Array.<string>
translate(text, substitution, singularTextopt) → {string}
Returns the translation for the specified text in the currently loaded language. If no translation exists, the text is returned untranslated (but with substitutions applied, if specified).
Substitutions in the translated string can be done with the substitution
parameter. If a number or a string is specified, then it will replace the first
appearance of "%s" in the translated string. If substitution
is a string array, then each of its values will replace each appearance "%s"
in the translated string. Note that substitution strings must be translated beforehand,
if they require so.
To get the translation for a message id, use getString.
Parameters:
| Name | Type | Attributes | Description |
|---|---|---|---|
text |
string | The text to be translated. |
|
substitution |
number | string | !Array.<string> | null | One or more substitution values (optional). |
|
singularText |
string |
<optional> |
The text to translate instead of 'text' when 'substitution' equals 1. |
Returns:
- Type
- string