Download Manual Download

Navigation Mobile menu

Internationalization

The Internationalization plugin provides tools to manage the localization of a project. This includes facilitating translations, pluralization, formatting dates for the user's locale, and so on.

See the built-in example project for a thorough example showing the various internationalization features.

Scripting

This object has no script interface, because when using JavaScript or TypeScript coding you can use the browser built-in Intl object.

Locales

Locales - which specify a region, language or dialect - are specified using standardized BCP 47 language tag, also known as just a language tag. For example en-US refers to US English, en-GB refers to British English, pt-BR refers to Brazilian Portuguese, and so on.

The translation file

The plugin can be loaded with translation information through event sheets, but the most common use case is to have all the strings for a given language in a separate file and load that using the Load from JSON action. A bare-bones example of such file would be as follows:

{
	"locale": "en-GB",
	"strings": {
		"foo": "example localized string",
		"bar": {
			"baz": "more localized text"
		}
	}
}

A language file is a JSON file, with two distinct keys.

The "strings" key is mandatory, all the localized text should be nested inside it. It can contain any valid JSON - how it is organized is entirely up to the user to decide what is more convenient. Trying to load a file without this key will result in an error.

The "locale" key is optional and is used when loading to indicate to what language the file corresponds to. If the key is not present then the content of the file will be associated with the locale the Internationalization plugin is currently set to. If the key contains a value which can not be parsed into a valid locale, an error will be thrown when loading.

Loading an Internationalization file

To load an internationalization file do the following:

Use the AJAX plugin to request the file.
In the AJAX On Complete trigger, use the Load from JSON action of the Internationalization plugin to load the AJAX data.

Following those steps it is possible to load a localization file for each locale that needs it.

Looking up localized strings

Once the plugin has the data for the required locales, the next step is to look up the strings to use them where needed. To do that do the following:

Use the Set locale action
Use the Lookup expression with the appropriate path

Nesting, Push and Pop

In the case of having a few strings that need to be localized it can be easy enough to just have all of them at the root of the "strings" key in the localization file. As the amount of text that needs localization increases it can be useful to group related strings together to keep the localization files tidy.

To make the lookup for a nested string you can do two things:

Absolute path

Include the absolute path to the string you are looking for in the argument of the Lookup expression. Dots can be used to navigate to nested JSON keys.

This option is straight forward and can be convenient in isolated cases.

Relative path

Push the context where the strings you are looking for are in the localization file and then use relative paths when using the Lookup expression. A relative path begins with a dot, and is appended to the current context.

In the case of having many strings in the same context it can be useful to use relative paths to avoid duplication.

When using relative paths always remember to have a corresponding Pop context action for each Push context action.

Substitutions

By using substitutions it is possible to produce dynamic results at runtime, take the following example:

{
	"locale": "en-GB",
	"strings": {
		"test": "Hello {0} {1}"
	}
}

The string has two placeholders that can be replaced at runtime if additional values are provided when using the Lookup expression. There can be any amount of placeholders and the number in between the curly braces refers to the order of the arguments passed to Lookup.

Example 1

The output of that example is the string "Hello Good Morning".

If there are more placeholders than arguments, like in the example bellow, then the placeholders with no matching argument are left unchanged in the final result

Example 2

The output of that example is the string "Hello Good {1}".

Plural rules

Following is a simple example of a localization file set up with a plural rule for British English.

{
	"locale": "en-GB",
	"strings": {
		"plural-example": {
			"one": "{0} Pig",
			"other": "{0} Pigs"
		}
	}
}

In order to look up the plural form the LookupPlural expression is used passing in an additional value which is used to decide which plural form will be used.

Example 1

That example would yield the string "1 Pig".

Example 2

That example would yield the string "2 Pigs".

Pluralization in other languages other than English

English is a relatively simple language when it comes to pluralization, as there are only two plural categories: "one" and "other" which refer to single units and more than one (or zero) respectively.

Other languages might be more complex in this regard. To find out how many categories and the name each category has, use the following expressions to print out the values and see what keys your localization files need.

PluralCategoryCount will return the total amount of categories for the current locale.

PluralCategoryAt(index) will return the name of the plural category with the provided zero-based index.

As an example, the locale "ar-EG" (Egypt Arabic) has six different plural categories, "few", "many", "one", "two", "zero" and "other". So a localization file for this language which uses plural rules should provide translations for each category.