# Multilingual Support

Vela's capabilities cover multiple countries and regions. After the framework supports multilingual capabilities, a single JS application product (a single RPK file) can simultaneously support switching between multiple language versions. Developers do not need to develop multiple source code projects in different languages, avoiding difficulties in project maintenance.

Using the system's default language, the method for developers to configure multilingual support is very simple, requiring only two steps: defining resources and referencing resources.

# Defining Resource Files

Resource files are used to store business information definitions in multiple languages. Similar to other technology platforms (which use properties files or xml files), the JS application platform uses JSON files to save resource definitions.

Define an i18n folder under the project's src directory and place resource definition files for each language region inside it.

# Resource File Naming, Lookup Rules, and Recommendations

File names can use the language and country information obtained from the current system, for example, file names can be defined as: zh-CN.json, zh.json.

If the developer's current product only plans to support one language but still wants to utilize multilingual capabilities, simply declare a file named defaults.json.

The matching priority for JSON file names stops at the first match found; otherwise, it continues to the next level.

Priority Matching Rules are as follows:

<language code>-<country code>

<language code>

defaults

The first file in the default i18n configuration

Naming Recommendations:

For precise matching of language + region for multilingual configuration, it is recommended to use <language code>-<country code>.json to name resource files.
For configurations that do not require matching regions, it is recommended to use <language code>.json to name resource files.
defaults.json can be used alone as a default option or in combination with the above two methods.
It is not recommended to use the system's final fallback default first file solution, as it may result in unexpected display outcomes.

Warm Tip

Refer to Supported Language List for <language code>-<country code>.

# Configuration Syntax Supported by Resource Files

# Basic Text Configuration

{
  "message": {
    "hello": "hello world"
  }
}

# Array Configuration

Matching will serialize the data content into text output. This type of configuration does not support mixing with interpolation syntax.

{
  "message": {
    "array": ["a", 2, {"c": 3}]
  }
}

# Named Interpolation Configuration

Supports the use of {} placeholders for named interpolation. During invocation, substitute placeholder content is passed through named parameters.

{
  "message": {
    "hello": "{msg} world"
  }
}

# List Interpolation Configuration

Supports the use of {} placeholders for list interpolation. By configuring list index values, substitute placeholder content is passed through an alternative list during invocation.

{
  "message": {
    "hello": "{0} world"
  }
}

# Singular/Plural Syntax Configuration

Supports the use of | placeholders for singular/plural syntax configuration. Different options are separated by placeholders.

{
  "message": {
    "car": "car | cars",
  }
}

# Referencing Resources in Pages

Multilingual configuration is primarily implemented through the $t and $tc functions on the ViewModel instance. These methods can be used in <template> or <script>.

# Simple Formatting Method

this.$t(path, opts)

Parameter Descriptions:

Parameter	Type	Required	Description
path	String	Yes	The resource path to retrieve multilingual configuration, with object values connected by dots, e.g., "message.hello"
opts	Array \| Object	No	Configuration items for interpolation replacement, can be passed as an object or array, used in conjunction with configuration interpolation If an object is passed, specify the named key configured for parameter passing If an array is passed, the value is the index of the list interpolation configuration in the passed list

Usage Examples:

Example of retrieving values corresponding to Basic Text Configuration:

<template>
  <div>
    <!-- Display result: hello world -->
    <text>{{ $t('message.hello') }}</text>
  </div>
</template>

<script>
  export default {
    onInit () {
      // Simple formatting:
      console.log(this.$t('message.hello')) // hello world
    }
  }
</script>

Example of retrieving values corresponding to Array Configuration:

<template>
  <div>
    <!-- Directly display array, result: ["a", 2, {"c": 3}] -->
    <text>{{ $t('message.array') }}</text>
  </div>
</template>

<script>
  export default {
    onInit () {
      // Simple formatting:
      console.log(this.$t('message.array')) // ["a", 2, {"c": 3}]
    }
  }
</script>

Example of retrieving values corresponding to Named Interpolation Configuration:

<template>
  <div>
    <!-- Display result: hello world -->
    <text>{{ $t('message.hello', { msg: 'hello' }) }}</text>
  </div>
</template>

<script>
  export default {
    onInit () {
      // Simple formatting:
      console.log(this.$t('message.hello', { msg: 'hello' }))  // hello world
    }
  }
</script>

Example of retrieving values corresponding to List Interpolation Configuration:

<template>
  <div>
    <!-- Display result: hello world -->
    <text>{{ $t('message.hello', ['hello', 'hi']) }}</text>
  </div>
</template>

<script>
  export default {
    onInit () {
      // Simple formatting:
      console.log(this.$t('message.hello', ['hello', 'hi'])) // hello world
    }
  }
</script>

# Singular/Plural Formatting Method

this.$tc(path, choice, opts)

Parameter Descriptions:

Parameter	Type	Required	Description
path	String	Yes	The resource path to retrieve multilingual configuration, with object values connected by dots, e.g., "message.hello"
choice	Number	No	Used to determine which option's value to use. If no specific value is passed, the default is singular. Can also be used for interpolation display when the third parameter is not passed Special Value Descriptions: Value must be an integer, error parameters will not display and return an empty string Singular/plural determination ignores positive/negative signs Two-segment format treats 0 as even
opts	Array \| Object	No	Configuration items for interpolation replacement, can be passed as an object or array, used in conjunction with configuration interpolation If an object is passed, specify the named key configured for parameter passing If an array is passed, the value is the index of the list interpolation configuration in the passed list

Description of choice Singular/Plural Configuration:

Currently, singular/plural configurations in resource files support two writing styles and support mixing with interpolation syntax.

Two-segment configuration: singular|plural;

Three-segment configuration: empty value|singular|plural.

Configuration Examples:

{
  "message": {
    "car": "car | cars", // Two-segment configuration
    "apple": "no apples | one apple | {count} apples" // Three-segment configuration
  }
}

Usage Examples:

<template>
  <div>
    <!-- Two-segment singular/plural -->
    <!-- Display result: cars -->
    <text>{{ $tc('message.car', 0) }}</text>
    <!-- Display result: car -->
    <text>{{ $tc('message.car', 1) }}</text>
    <!-- Display result: cars -->
    <text>{{ $tc('message.car', 2) }}</text>

    <!-- Three-segment singular/plural -->
    <!-- Display result: no apples -->
    <text>{{ $tc('message.apple', 0) }}</text>
    <!-- Display result: one apple -->
    <text>{{ $tc('message.apple', 1) }}</text>
    <!-- Display result: 2 apples -->
    <text>{{ $tc('message.apple', 2) }}</text>
    <!-- Three-segment singular/plural mixed with interpolation usage -->
    <!-- Display result: 6 apples -->
    <text>{{ $tc('message.apple', 2, {count: 6}) }}</text>
  </div>
</template>

<script>
  export default {
    onInit () {
      // Two-segment singular/plural:
      console.log(this.$tc('message.car', 0)) // cars
      console.log(this.$tc('message.car', 1)) // car
      console.log(this.$tc('message.car', 2)) // cars

      // Three-segment singular/plural:
      console.log(this.$tc('message.apple', 0)) // no apples
      console.log(this.$tc('message.apple', 1)) // one apple
      console.log(this.$tc('message.apple', 2)) // 2 apples
      console.log(this.$tc('message.apple', 2, {count: 6})) // 6 apples
    }
  }
</script>

# Retrieving System Language

The above capabilities are used for formatting resource content. In certain scenarios, developers may need to retrieve the current system's locale language and make changes to complete different logical processing. For example:

Different locales correspond to different page layouts;
Developers provide users with the ability to set a specific language.

The framework's system.configuration provides related functionality, refer to the documentation: Application Configuration configuration.

# Callback After Changing Locale Language

When a user switches the locale language in system settings, the onConfigurationChanged callback is triggered, and the returned event.type value is locale.

For details, refer to the documentation.

Example code:

// Listen for language changes
onConfigurationChanged(event) {
  if (event && event.type && event.type === 'locale') {
    console.log('locale or language changed!')
  }
}

← Page Switching Background Running →