1# Multi-Language Capability
2
3Applications designed based on the JS UI framework apply to different countries and regions. With the multi-language capability, you do not need to develop application versions in different languages, and your users can switch between various locales. This also facilitates project maintenance.
4
5
6You only need to perform operations in [Defining Resource Files](#defining-resource-files) and [Referencing Resources](#referencing-resources) to use the multi-language capability of this framework. For details about how to obtain the current system language, see [Obtaining the Language](#obtaining-the-language).
7
8
9## Defining Resource Files
10
11Resource files store application content in multiple languages. This framework uses JSON files to store resource definitions.
12
13Place the resource file of each locale in the i18n directory described in [File Organization](js-framework-file.md). Resource files should be named in _language-script-region_.json format. For example, the resource file for Hong Kong(China) in the traditional script is named zh-Hant-HK. You can omit the region, for example, zh-CN for simplified Chinese, or omit both the script and region, for example, zh for Chinese.
14
15```
16language[-script-region].json
17```
18
19The following table describes the requirements for the qualifiers of resource file names.
20
21Table 1 Requirements for qualifier values
22
23| Qualifier Type| Description and Value Range                                 |
24| ----- | ---------------------------------------- |
25| Language   | Indicates the language used by the device. The value consists of two or three lowercase letters. For example, **zh** indicates Chinese, **en** indicates English, and **mai** indicates Maithili.<br>For details about the value range, refer to **ISO 639** (codes for the representation of names of languages).|
26| Script   | Indicates the script type used by the device. The value starts with one uppercase letter followed by three lowercase letters. For example, **Hans** indicates simplified Chinese, and **Hant** indicates traditional Chinese.<br>For details about the value range, refer to **ISO 15924** (codes for the representation of names of scripts).|
27| Country/Region| Indicates the country or region where the user is located. The value consists of two or three uppercase letters or three digits. For example, **CN** indicates China, and **GB** indicates the United Kingdom.<br>For details about the value range, refer to **ISO 3166-1** (codes for the representation of names of countries and their subdivisions).|
28
29If there is no resource file of the locale that matches the system language, content in the **en-US.json** file will be used by default.
30
31The format of the resource file content is as follows:
32
33**en-US.json**
34
35```json
36{
37    "strings": {
38        "hello": "Hello world!",
39        "object": "Object parameter substitution-{name}",
40        "array": "Array type parameter substitution-{0}",
41        "symbol": "@#$%^&*()_+-={}[]\\|:;\"'<>,./?"
42    },
43
44    "files": {
45        "image": "image/en_picture.PNG"
46    }
47}
48```
49
50
51Different languages have different matching rules for singular and plural forms. In the resource file, **zero**, **one**, **two**, **few**, **many**, and **other** are used to define the string content in different singular and plural forms. For example, there is only the **other** scenario in Chinese since the language does not have singular and plural forms. **one** and **other** scenarios are applicable to English. All six scenarios are needed for Arabic.
52
53
54The following example takes **en-US.json** and **ar-AE.json** as examples:
55
56**en-US.json**
57
58```json
59{
60    "strings": {
61        "people": {
62            "one": "one person",
63            "other": "{count} people"
64        }
65    }
66}
67```
68
69
70**ar-AE.json**
71
72```json
73{
74    "strings": {
75        "people": {
76            "zero": "لا أحد",
77            "one": "وحده",
78            "two": "اثنان",
79            "few": "ستة اشخاص",
80            "many": "خمسون شخص",
81            "other": "مائة شخص"
82        }
83    }
84}
85```
86
87
88## Referencing Resources
89
90Multi-language syntax used on application development pages (including simple formatting and singular-plural formatting) can be used in **.hml** or **.js** files.
91
92- Simple formatting
93
94Use the **$t** function to reference to resources of different locales. The **$t** function is available for both **.hml** and **.js** files. The system displays content based on a resource file path specified via **$t** and the specified resource file whose locale matches the current system language.
95
96Table 2 Simple formatting
97
98  | Attribute| Type    | Parameter             | Mandatory| Description                                                  |
99  | ---- | -------- | ----------------- | ---- | ------------------------------------------------------ |
100| $t   | Function | See Table 3.| Yes  | Sets the parameters based on the system language, for example, **this.$t('strings.hello')**.|
101
102Table 3 $t function parameters
103
104  | Parameter  | Type         | Mandatory| Description                                                        |
105  | ------ | ------------- | ---- | ------------------------------------------------------------ |
106  | path   | string        | Yes  | Path of the language resource key.                                                  |
107| params | Array\|Object | No  | Content used to replace placeholders during runtime. There are two types of placeholders available:<br>- Named placeholder, for example, **{name}**. The actual content must be of the object type, for example, **$t('strings.object', {name:'Hello world'})**.<br> - Digit placeholder, for example, **{0}**. The actual content must be of the array type, for example, **$t('strings.array', [Hello world']**.|
108
109- Example code for simple formatting
110  ```html
111  <!-- xxx.hml -->
112  <div>
113    <!-- Display Hello world! without using a placeholder. -->
114    <text>{{ $t('strings.hello') }}</text>
115    <!-- Replace named placeholder {name} with Hello world and display it. -->
116    <text>{{ $t('strings.object', { name: 'Hello world' }) }}</text>
117    <!-- Replace digit placeholder {0} with Hello world and display it. -->
118    <text>{{ $t('strings.array', ['Hello world']) }}</text>
119    <!-- Obtain the resource content from the .js file and display Hello world. -->
120    <text>{{ hello }}</text>
121    <!-- Obtain the resource content from the .js file, replace named placeholder {name} with Hello world, and display Substitution in an object: Hello world. -->
122    <text>{{ replaceObject }}</text>
123    <!-- Obtain the resource content from the .js file, replace digit placeholder {0} with Hello world, and display Substitution in an array: Hello world. -->
124    <text>{{ replaceArray }}</text>
125
126    <!-- Display the image in the specified file path. -->
127    <image src="{{ $t('files.image') }}" class="image"></image>
128    <!-- Obtain the image file path from the .js file and display the image. -->
129    <image src="{{ replaceSrc }}" class="image"></image>
130  </div>
131  ```
132
133  ```js
134  // xxx.js
135  // The following example uses the $t function in the .js file.
136  export default {
137    data: {
138      hello: '',
139      replaceObject: '',
140      replaceArray: '',
141      replaceSrc: '',
142    },
143    onInit() {
144      this.hello = this.$t('strings.hello');
145      this.replaceObject = this.$t('strings.object', { name: 'Hello world' });
146      this.replaceArray = this.$t('strings.array', ['Hello world']);
147      this.replaceSrc = this.$t('files.image');
148    },
149  }
150  ```
151
152- Singular-plural formatting
153
154  Table 4 Singular-plural formatting
155
156  | Attribute| Type    | Parameter              | Mandatory| Description                                                        |
157  | ---- | -------- | ------------------ | ---- | ------------------------------------------------------------ |
158  | $tc  | Function | See Table 5.| Yes  | Converts between the singular and plural forms based on the system language, for example, **this.$tc('strings.people')**.<br>**NOTE**<br>The resource content is distinguished by the following JSON keys: **zero**, **one**, **two**, **few**, **many**, and **other**.|
159
160  Table 5 $tc function parameters
161
162  | Parameter | Type  | Mandatory| Description        |
163  | ----- | ------ | ---- | ------------ |
164  | path  | string | Yes  | Path of the language resource key.  |
165  | count | number | Yes  | Number.|
166
167- Example code for singular-plural formatting
168  ```html
169  <!--xxx.hml-->
170  <div>
171    <!-- When the value 0 is passed, "0 people" matches the Arabic string whose key is zero. -->
172    <text>{{ $tc('strings.people', 0) }}</text>
173    <!-- When the value 1 is passed, "1 person" matches the Arabic string whose key is one. -->
174    <text>{{ $tc('strings.people', 1) }}</text>
175    <!-- When the value 2 is passed, "2 people" matches the Arabic string whose key is two. -->
176    <text>{{ $tc('strings.people', 2) }}</text>
177    <!-- When the value 6 is passed, "6 people" matches the Arabic string whose key is few. -->
178    <text>{{ $tc('strings.people', 6) }}</text>
179    <!-- When the value 50 is passed, "50 people" matches the Arabic string whose key is many. -->
180    <text>{{ $tc('strings.people', 50) }}</text>
181    <!-- When the value 100 is passed, "100 people" matches the Arabic string whose key is other. -->
182    <text>{{ $tc('strings.people', 100) }}</text>
183  </div>
184  ```
185
186
187## Obtaining the Language
188
189For details about how to obtain the language, see [Configuration](../reference/apis-ability-kit/js-apis-app-ability-configuration.md).
190