OpenHarmony工具集如何进行国际化支持

OpenHarmony工具集国际化支持实践

一 资源侧多语言配置

• 资源目录与文件组织：在工程的 resources 目录下按语言/地区创建子目录，常见结构为 base/element/string.json（默认资源）与 zh/element/string.json、en/element/string.json 等；文件名遵循 语言-地区.json 规范（如 en-US.json）。ArkUI/eTS 中通过资源管理引用，如 $r(‘app.string.key’) 或 $(‘app.string.key’)。JS/ETS 场景亦可在 i18n/语言-地区.json 中定义并在界面绑定使用。为兼容旧工程，亦可采用 zh_CN 形式目录。示例：
  • resources/base/element/string.json { “string”: [ { “name”: “app_name”, “value”: “MyTool” }, { “name”: “desc”, “value”: “A useful toolkit.” } ] }
  • resources/zh/element/string.json { “string”: [ { “name”: “app_name”, “value”: “我的工具” }, { “name”: “desc”, “value”: “一个实用工具集。” } ] }
  • 使用：$r(‘app.string.app_name’) 或 $(‘app.string.app_name’)。JS 侧亦可在 i18n/zh-CN.json 中定义并在模板中绑定。上述方式无需引入三方库，原生支持多语言资源组织与引用。

二 运行时获取与格式化

• 系统与区域信息：使用 @ohos.i18n 获取/设置系统语言、地区、Locale、24小时制、RTL 等，例如 getSystemLanguage()、getSystemRegion()、getSystemLocale()、is24HourClock()、isRTL()，用于界面文案方向、时间制式、数字/日期本地化前置判断。
• 数据与规则格式化：使用 @ohos.intl 进行本地化格式化，如 Intl.Locale、Intl.DateTimeFormat、Intl.NumberFormat，适配不同地区的日期、时间、数字、货币、百分比等显示规则。
• 系统级设置能力：如需在工具集中提供“系统语言/地区/时区”设置入口，可调用 setSystemLanguage()、setSystemRegion()、setSystemLocale()；涉及系统配置变更需声明权限（见下节）。示例：
  • import i18n from ‘@ohos.i18n’;
  • import intl from ‘@ohos.intl’;
  • const lang = i18n.getSystemLanguage(); // 如 zh-Hans-CN
  • const fmt = new intl.DateTimeFormat(lang, { dateStyle: ‘full’, timeStyle: ‘long’ });
  • console.info(fmt.format(new Date()));

三 权限与系统设置

• 当工具集包含“修改系统语言、地区、时区或时间”的功能时，需在 module.json5 的 requestPermissions 中声明：
  • ohos.permission.UPDATE_CONFIGURATION：更新系统配置
  • ohos.permission.SET_TIME_ZONE：设置时区
  • ohos.permission.SET_TIME：设置时间
• 注意：上述权限通常仅对系统应用或具备系统授权的应用开放，普通应用调用可能受限；工具集应做好权限检测与降级处理（如无权限则仅提供应用内语言切换）。

四 语言切换与动态更新

• 应用内语言切换（推荐）：工具集作为应用提供多语言时，优先采用“应用内语言包”方案，切换时重建所需页面/组件或局部刷新文本资源，避免依赖系统设置。资源侧通过 $r(‘app.string.key’) 自动按当前资源目录匹配，无需重启应用。
• 系统级语言切换：若工具集需要联动系统语言，调用 i18n.setSystemLanguage/setSystemRegion/setSystemLocale 并申请权限；切换后系统会发送配置变更事件，工具集需监听并刷新界面。
• 动态资源与RTL：对含文本的外部资源（如 Lottie 动画），可在运行时做“标识替换”或按语言目录加载差异化资源，并在 isRTL(locale) 为 true 时调整布局方向、镜像等，保证阿拉伯语等 RTL 语言体验。

五 工具集落地清单

• 资源侧：建立 base + 多语言目录 与 string.json，统一 name 命名，提供 zh/zh-CN、en/en-US 等覆盖；为含计数的词条补充复数键（如 zero/one/other）。
• 代码侧：界面文本统一用 $r(‘app.string.xxx’)；涉及日期/数字/货币用 @ohos.intl；需要系统级能力时再调用 @ohos.i18n 并处理权限与失败回退。
• 质量与体验：覆盖 LTR/RTL、不同 12/24 小时制、不同 千分位/小数点 与 日期格式；提供“跟随系统/应用内选择”两种模式；在设置页明确权限边界与不可用场景提示。