--- title: '国际化' description: '蓝河应用平台的能力会覆盖多个国家地区，平台支持国际化(i18n)的能力后，可以做到让一个蓝河应用产品（一个 RPK 文件）同时支持多个语言版本的切换，开发者无需开发多个不同语言的源码项目，避免给项目维护带来困难。' lastUpdated: 2025-10-09T03:25:10.000Z --- 蓝河应用平台的能力会覆盖多个国家地区，平台支持国际化(i18n)的能力后，可以做到让一个蓝河应用产品（一个 RPK 文件）同时支持多个语言版本的切换，开发者无需开发多个不同语言的源码项目，避免给项目维护带来困难。 使用系统默认的语言，开发者配置国际化的方式非常简单，只需要`定义资源`与`引用资源`两个步骤即可；如果允许用户在蓝河应用中修改地区语言，请参考第三步`获取更新语言`； ## 定义资源文件 资源文件用于存放多个语言的业务信息定义，与其它技术平台类似（它们使用`properties文件`或者`xml文件`的格式），蓝河应用平台使用`JSON文件`保存资源定义； 在项目源码`src目录`下定义`i18n文件夹`，内部放置每个语言地区下的资源定义文件即可；其中文件名定义为：`zh-CN.json`、`zh.json`； 每个 JSON 文件的内容格式如下： ```json { "message": { "pageA": { "text": "pure-text-content", "format": { "object": "type-{name}", "array": "type-{0}" }, "plurals": { "double": "car | cars", "three": "no apples | one apple | {count} apples", "format": { "object": "type-{name}", "array": "type-{0}" } } } } } ``` 页面中通过`message.pageA.text`类似的`path`引用对应内容`"pure-text-content"`； ## 页面中引用资源 页面中 i18n 的使用语法，主要体现在 ViewModel 的几个函数上，如：`$t`，这些方法可以在``中使用； 如下代码所示： ```html ``` ### 简单格式化方法 | 属性 | 类型 | 参数 | 描述 | | --- | --- | --- | --- | | $t | Function | path: String 资源路径 arg0: object | array 格式化参数，非必要参数，根据系统语言完成简单的替换：`this.$t('message.pageA.text')` | 比如： ```ts // 示例：无额外参数的格式化 // 输出："pure-text-content" this.$t('message.pageA.text') // 示例：额外参数为对象，替换引用内容中的绑定 // 输出："type-arg-object" this.$t('message.pageA.format.object', { name: 'arg-object' }) ``` ### 单复数格式化方法 | 属性 | 类型 | 参数 | 描述 | | --- | --- | --- | --- | | $tc | Function | path: String 资源路径 count: number 要表达的值 | 根据系统语言完成单复数替换：`this.$tc('message.plurals.double')`，注意：定义资源的内容通过 | 分隔为多个选项 | 比如： ```ts // 示例：message的值为两个选项时，传递数值不为单数 // 输出："cars" this.$tc('message.pageA.plurals.double', 0) // 示例：message的值为两个选项时，传递数值为单数 // 输出："car" this.$tc('message.pageA.plurals.double', 1) // 示例：message的值为两个选项时，传递数值不为单数 // 输出："cars" this.$tc('message.pageA.plurals.double', 2) // 示例：message的值为三个及以上的选项时，传递数值不为单数 // 输出："no apples" this.$tc('message.pageA.plurals.three', 0) // 示例：message的值为三个及以上的选项时，传递数值为单数 // 输出："one apple" this.$tc('message.pageA.plurals.three', 1) // 示例：message的值为三个及以上的选项时，传递数值不为单数 // 输出："10 apples" this.$tc('message.pageA.plurals.three', 10) ``` ### manifest 中的 name 的国际化 此时可使用字符串模板声明，形如：${appName} 例如下面： ```json { "package": "com.example.i18n", "name": "${appName}", "versionName": "1.0.0", "versionCode": 1 } ``` 此时 i18n 也必须有相应的配置信息 ```json // en.json { "appName": "myApp" } ``` ```json // zh-CN.json { "appName": "我的应用" } ``` ### 获取更新语言 上面的能力用于资源内容的格式化，在某些场景下开发者可能需要获取当前系统的地区语言`locale`并进行更改，来完成不同的逻辑处理： - 比如：不同的 locale 对应的页面布局不同； - 比如：开发者为用户提供设置某种语言的能力； 此时开发者，可以通过`blueos.app.configuration`接口来完成 比如： ```ts import configuration from '@blueos.app.configuration' // 获取locale，后续开发者可以将locale设置为VM中的data属性，并在模板中判断以区分不同的布局 const localeObject = configuration.getLocale() // 转换为字符串格式，如：'zh'或者'zh-CN' const locale = [localeObject.language, localeObject.countryOrRegion].filter((n) => !!n).join('-') console.info(`获取当前locale：${locale}`) ``` 设置多当前语言(setLocale)为系统接口，普通应用无法调用。 ```ts import configuration from '@blueos.app.configuration' // 设置locale成功后，通过VM的生命周期函数 onConfigurationChanged 触发 configuration.setLocale({ language: 'zh', countryOrRegion: 'CN', }) ``` ### 修改地区语言后的回调 当用户在系统设置或者通过 configuration.setLocale 切换地区语言，都会触发 onConfigurationChanged 回调，且返回来的 event.type 值为`locale` 示例代码 ```ts // 监听语言、地区变化 onConfigurationChanged(event) { if (event && event.type && event.type === 'locale') { console.log('locale or language changed!') } } ```