Skip to main content

Internationalization

Internationalization

Internationalization is used to translate the interface into different languages for users of different languages.

Internationalization Resources

The internationalization mechanism requires developers to first write the application's internationalization resource files and then use them in the component code. Internationalization resources are JSON files stored in the application's src/i18n directory (developers need to create this folder first), with each file named after a language code, for example:

src                # Project source code path
└─ i18n            # Internationalization resource folder
   ├─ default.json # Default fallback language
   ├─ ja.json      # Japanese translation file
   ├─ it.json      # Italian translation file
   └─ zh-CN.json   # Simplified Chinese translation file

As shown in the example, default.json is the translation file for the default fallback language. When the text to be translated is not available in the selected language, the rules of this translation file will be used.

The content of an internationalization resource file is a JSON object in the following format:

// default.json
{
  "helloWorld": "Hello, world!"
}
// zh-CN.json
{
  "helloWorld": "你好，世界！"
}

The values of this JSON object are the translation texts in the target language, while the keys are used to index the translation texts in the code. Each key corresponds to translation text with the same meaning across internationalization resource files of multiple languages. For example, the helloWorld key corresponds to the translation text "Hello, world!" in English and "你好，世界！" in Chinese.

default.json

Unlike general language internationalization files, default.json is also used for falling back on translation texts not defined in the current language. That is, if a key for an internationalization string is not defined in the JSON file of that language but exists in default.json, the translation from the latter will be used.

When a key does not exist in any of the above internationalization files, the internationalization framework will directly return the key itself.

Using Internationalization Text

$t() Function

$t() is a global function used to obtain internationalization text. Its signature is:

function $t(key: string): string

key is the key to be translated, and the return value is the corresponding internationalization text in the current language. If this key-value pair does not exist in the internationalization resources, the key itself will be returned.

This function is typically used in component code, for example:

<p>{{ $t('helloWorld') }}</p>

It can also be used in JavaScript code:

console.log($t('helloWorld'))

t Command

Native components support the t command for automatic translation of internationalization text:

<p t>helloWorld</p>

The <p> component in the example contains an attribute named t (which is actually a command). This command is equivalent to automatically calling the $t() function with the text child node helloWorld as an argument and using the returned internationalization text to set the text content of the <p> component. In template code, the t command is simpler to use than the $t() function.

The t command also supports being used as an attribute prefix for native components, for example:

<p t:text="helloWorld" />

Similar to the standalone t command, the attribute value string helloWorld will be used as a key to query the corresponding internationalization text. This is also more convenient than the equivalent code using the $t() function:

<p :text="$t('helloWorld')" />

Tips

The t command currently only supports native components and has no effect in custom components.

When the t command is available, please prioritize using the t command over the $t() function, as the implementation of the t command ensures better performance.

Switching Languages

When the application switches languages, the reactive properties of all components will be recalculated. At this time, the internationalization text will be re-queried, so there is no need to update the interface manually. However, $t() functions called outside the reactive framework do not have these effects.

Cached computed property values are not recalculated when switching languages, so translation text obtained by calling $t() in the get() method of a computed property will not be re-fetched.

Obtaining Internationalization Configuration

You can access the application's internationalization configuration through the @system.i18n module. You can also listen for locale changes through the application's onLocaleChanged() life cycle function.

Glyphix framework