OpenHarmony高级UI组件如何支持多语言

OpenHarmony 高级 UI 组件多语言适配指南

一 资源与目录规范

• 在工程 resources 下按语言/地区划分目录，使用限定符如 zh_CN、en_US、ar。默认兜底用 base。每个限定符目录的 element 下放置 string.json（复数可用 plural.json）。示例：
  • entry/src/main/resources/
    • base/element/string.json
    • zh_CN/element/string.json
    • en_US/element/string.json
    • ar/element/string.json
• 资源索引文件 res/resources.json 中登记所有限定符目录，确保打包后可被匹配：
  • {“name”:“base”,“path”:“resources/base”},{“name”:“zh_CN”,“path”:“resources/zh_CN”}…
• 字符串键值化与占位：
  • {“hello”:“你好，{name}！”,“file_count”:“{count} 个文件”}
• 含文字的图片/图标也按相同限定符拆分，避免语义冲突与布局错乱。

二 在 ArkUI 高级组件中使用多语言

• 文本与富文本
  • 使用 $r(‘app.string.key’) 或 $string:key 在组件属性中直接绑定资源键，系统按当前 Locale 自动匹配与回退：
    • Text($r(‘app.string.hello’, { name: ‘World’ }))
    • // 若支持复数：PluralRules/plural 资源配合格式化
• 复数与数量
  • 在 string.json 定义复数键，运行时按数量选择文案；或使用 resourceManager.getPluralStringValue(id, num) 获取复数化字符串。
• 日期、数字、货币的区域化
  • 使用 @ohos.intl 进行本地化格式化，避免硬编码格式：
    • new intl.DateTimeFormat(locale, { dateStyle:‘medium’, timeStyle:‘short’ }).format(date)
    • new intl.NumberFormat(locale, { style:‘currency’, currency:‘CNY’ }).format(199.99)
• RTL 与布局方向
  • 阿拉伯语等 RTL 语言需镜像布局：优先使用 start/end 而非 left/right；必要时为 RTL 单独提供文案与图标资源。

三 应用内动态切换语言

• 基本思路
  • 将用户选择持久化（如 Preferences），在运行时构建带覆盖 Locale 的 ResourceManager，并通过状态管理/依赖注入让 UI 重建或局部刷新。
• 最小可用示例（单例服务）
  • i18n/LanguageService.ts
    • import i18n from ‘@ohos.i18n’; import resourceManager from ‘@ohos.resourceManager’; import preferences from ‘@ohos.data.preferences’;
    • type LangOption = ‘system’ | ‘zh_CN’ | ‘en_US’ | ‘ar’;
    • class LanguageService { private static inst: LanguageService; private current: LangOption = ‘system’; private rm?: resourceManager.ResourceManager; private listeners: Array<() => void> = []; static get() { return this.inst ??= new LanguageService(); } async init(context: any) { const pref = await preferences.getPreferences(context, ‘i18n’); this.current = (await pref.get(‘lang’, ‘system’)) as LangOption; await this.apply(context); } onChange(fn: () => void) { this.listeners.push(fn); } getResourceManager() { return this.rm; } getCurrent() { return this.current; } async setLang(context: any, lang: LangOption) { this.current = lang; await preferences.put(‘lang’, lang).then(() => preferences.flush(context)); await this.apply(context); this.listeners.forEach(fn => fn()); // 通知 UI 刷新 } private async apply(context: any) { const cfg = { locale: this.current === ‘system’ ? ‘’ : this.current }; this.rm = await resourceManager.createConfiguration(context, cfg); // 或 getResourceManager(config) } }
• 在 UI 中使用
  • 通过服务获取 ResourceManager 或直接用 $r 读取；语言变更后触发页面重建或局部更新（如路由重建、状态驱动刷新）。
• 系统语言变更监听
  • 通过 @ohos.i18n.System 获取系统语言/地区，必要时在 Ability/Application 层监听并同步应用内状态（如返回前台时重新 apply）。

四 常见坑与最佳实践

• 不要硬编码文案或格式；所有面向用户的文本、空态、错误提示、按钮文案统一走 string.json。
• 用参数化占位替代拼接：如 “{count} 个文件”，避免复数与性别带来的拼接错误。
• 资源登记别遗漏：新增 zh_HK/ar_SA 等目录后，记得在 res/resources.json 中登记，否则匹配不到。
• 图片/图标含文字需按限定符拆分；RTL 语言提供镜像图标与文案。
• 测试三板斧：伪本地化长文本（检查截断/换行）、极端长度与变体、系统语言切换与夜间模式/字体放大联动。