Multi-language Capability

Defining a Resource File

The quick app platform uses a JSON resource file to store service information definitions of multiple languages. Similarly, other technical platforms usually define service information in .properties or .xml files.

Define the i18n folder in the src directory of the source code project and save the resource file for each language/region in the folder. If a language/region has multiple resource files, file matching is performed by priority. For example, for zh-CN, the matching sequence is as follows: zh-CN -> zh -> zh-* -> defaults. If there are multiple zh-* files, they are sorted in ascending alphabetical order.

If your app is planned to support only one language, but you still need to use the formatting, singular-plural conversion, and localization of multi-language support, just declare the defaults.json file.

The format of a JSON file is as follows:

{
    "message": {
        "appName":"Quick App Sample",
        "pageA": {
            "pageTitle": "Quick App feature display",
            "text": "pure-text-content",
            "format": {
                "object": "type-{name}",
                "array": "type-{0}"
            },
            "array": [
                "item-type-string",
                {
                    "key": "item-type-object-attribute"
                },
                ["item-type-array"]
            ],
            "plurals": {
                "double": "car | cars",
                "three": "no apples | one apple | {count} apples",
                "format": {
                    "object": "type-{name}",
                    "array": "type-{0}"
                }
            }
        }
    }
}

A page can reference pure-text-content using a path similar to message.pageA.text.

Referencing Resources on a Page

The functions in ViewModel, for example, $t, implement multi-language capabilities. You can call these functions in the template or script element.

The sample code is as follows:

<template>
    <div>
        <text>{{ $t('message.pageA.text') }}</text>
        <text>{{ $t('message.pageA.format.object', { name: 'arg-object' }) }}</text>
        <text>{{ $t('message.pageA.format.array', ['arg-array']) }}</text>
    </div>
</template>
<script>
    export default {
        onInit () {
            // Simple formatting:
            this.$t('message.pageA.text')
            this.$t('message.pageA.format.object', { name: 'arg-object' })
            this.$t('message.pageA.format.array', ['arg-array'])
        }
    }
</script>

[h2]Method for Simple Formatting

Sample code

// Sample 1: Formatting without additional parameters
// Output: "pure-text-content"
this.$t('message.pageA.text')
// Sample 2: The additional parameter is an object, which is used to replace the binding in the referenced content.
// Output: "type-arg-object"
this.$t('message.pageA.format.object', { name: 'arg-object' })
// Sample 3: The additional parameter is an array, which is used to replace the binding in the referenced content.
// Output: "type-arg-array"
this.$t('message.pageA.format.array', ['arg-array'])

[h2]Singular-Plural Conversion Method

Sample code

// Sample 1: When the value of message contains two options, the passed value is not the singular form.
// Output: "cars"
this.$tc('message.pageA.plurals.double', 0)
// Sample 2: When the value of message contains two options, the passed value is the singular form.
// Output: "car"
this.$tc('message.pageA.plurals.double', 1)
// Sample 3: When the value of message contains two options, the passed value is not the singular form.
// Output: "cars"
this.$tc('message.pageA.plurals.double', 2)
// Sample 4: When the value of message contains two options, the passed value is not the singular form.
// Output: "no apples"
this.$tc('message.pageA.plurals.three', 0)
// Sample 5: When the value of message contains three or more options, the passed value is the singular form.
// Output: "one apple"
this.$tc('message.pageA.plurals.three', 1)
// Sample 6: When the value of message contains three or more options, the passed value is not the singular form.
// Output: "10 apples"
this.$tc('message.pageA.plurals.three', 10)

Obtaining Language Updates

In some scenarios, you may need to obtain and change the locale of the current system to implement different logic processing. The page layout may vary according to the locale. You can provide the language change function for users by calling the system.configuration API. For details, please refer to App Configuration.

import configuration from '@system.configuration'
// Obtain the locale. You can set the locale to the data attribute in the VM and determine the locale in the template to distinguish layouts.
const localeObject = configuration.getLocale()
// Convert the locale to the character string format, for example, zh or zh-CN.
const locale = [localeObject.language, localeObject.countryOrRegion]
    .filter(n => !!n)
    .join('-')
console.info(`Obtain the current locale: ${locale}`)
import configuration from '@system.configuration'
// Triggered by the VM lifecycle function onConfigurationChanged after locale is set successfully.
configuration.setLocale({
  language: 'zh',
  countryOrRegion: 'CN'
})

Callback upon Language Switchover

The onConfigurationChanged callback is executed when a user modifies system settings or configuration.setLocale is called to change the language/region.

onConfigurationChanged(data) {
    // Output {"type":"locale"}
    console.info(JSON.stringify(data))
}

Internationalization Settings in the manifest.json File

Internationalize the app name and page title configured in the manifest.json file.

• App name: Set name to the parameter (for example, ${message.appName}) that defines the app name in the JSON file.
• Page title: Set titleBarText under display to the parameter (for example, ${message.pageA.pageTitle}) that defines the page title in the JSON file.