Xiaomi Vela JS APP

# Multilingual Support

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

Using the system's default language, developers can configure multilingual support with just two steps: defining resources and referencing resources.

# Defining Resource Files

Resource files are used to store business information definitions for multiple languages. Similar to other technical 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 product only plans to support one language but still wants to use multilingual capabilities, simply declare a file named defaults.json.

JSON file name matching priority: matching stops when a higher priority match is found; otherwise, it continues to the next level.

Priority Matching Rules:

<language code>-<country code>

<language code>

defaults

The default i18n configuration file is the first one.

Naming Recommendations:

  • For precise multilingual configuration matching both language and region, use <language code>-<country code>.json for resource file naming.

  • For configurations not needing region matching, use <language code>.json for resource file naming.

  • defaults.json can be used as a default option alone or in combination with the above two methods.

  • It is not recommended to use the system's final fallback default first option, as it may cause unexpected display results.

Reminder

<language code>-<country code> can refer to: Supported Language List.

# Resource File Supported Configuration Syntax

# Basic Text Configuration

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

# Array Configuration

When matched, the data content will be serialized and converted to text output. This configuration does not support mixing with interpolation syntax.

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

# Named Interpolation Configuration

Supports using {} placeholders for named interpolation. When called, pass the placeholder content through named parameters.

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

# List Interpolation Configuration

Supports using {} placeholders for list interpolation. By configuring the list value index, pass the alternative list during the call to replace the placeholder content with the indexed value.

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

# Singular/Plural Syntax Configuration

Supports using | placeholders for singular/plural syntax configuration. Different options are separated by placeholders.

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

# Referencing Resources in Pages

The use of multilingual configurations is mainly achieved 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 Description:

Parameter Type Required Description
path String Yes The resource path to get multilingual configuration, object values are accessed via dots, e.g., "message.hello"
opts Array | Object No Configuration items for interpolation replacement. Can pass an object or array. Used in conjunction with the interpolation configuration in the settings.
If passing an object, specify the named key of the configuration for parameter passing.
If passing an array, use the index value corresponding to the list interpolation configuration in the passed list.

Usage Example:

Example using 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 using array configuration:

<template>
  <div>
    <!-- Directly display the 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 using 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 using 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 Description:

Parameter Type Required Description
path String Yes The resource path to get multilingual configuration, object values are accessed via dots, e.g., "message.hello"
choice Number No Used to determine which option's value to use. Can also be used for interpolation display when the third parameter is not passed.
Special Value Description:
Value must be an integer; errors in parameters result in no display and return an empty string.
Singular/plural determination ignores positive/negative signs.
0 is treated as an even number.
opts Array | Object No Configuration items for interpolation replacement. Can pass an object or array. Used in conjunction with the interpolation configuration in the settings.
If passing an object, specify the named key of the configuration for parameter passing.
If passing an array, use the index value corresponding to the list interpolation configuration in the passed list.

Singular/Plural Configuration Description:

Currently, the resource file supports two writing methods for singular/plural and supports mixing with interpolation syntax.

Two-segment configuration: singular|plural;

Three-segment configuration: empty|singular|plural.

Configuration Example:

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

Usage Example:

<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 -->
    <!-- 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>

# Getting System Language

The above capabilities are used for formatting resource content. In some scenarios, developers may need to get the current system's locale and change it to complete different logical processing. For example:

  • Different locales correspond to different page layouts;

  • Developers provide users with the ability to set a certain language.

The framework's system.configuration provides relevant functions. For documentation, refer to: Application Configuration configuration.

# Callback After Modifying Locale Language

When the user switches the locale language in the system settings, the onConfigurationChanged callback will be triggered, and the returned event.type value will be 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!')
  }
}

← Background Running →

TOC
Defining Resource Files
Resource File Naming, Lookup Rules, and Recommendations
Resource File Supported Configuration Syntax
Referencing Resources in Pages
Simple Formatting Method
Singular/Plural Formatting Method
Getting System Language
Callback After Modifying Locale Language