OpenHarmony UI组件如何支持多语言切换

OpenHarmony UI组件多语言切换实践

一 资源与目录结构

• 在工程的 resources 目录下按语言与类别组织资源，文本统一放在 element/string.json。常见做法同时提供 base/element/string.json（默认/回退）与 zh/element/string.json、en/element/string.json（各语言）。示例：
  • resources/base/element/string.json { “strings”: [ {“name”: “app_name”, “value”: “天气助手”}, {“name”: “welcome”, “value”: “欢迎使用天气助手”}, {“name”: “weather_desc”, “value”: “今日天气晴朗，适宜外出”}, {“name”: “switch_lang”, “value”: “切换英文”} ] }
  • resources/en/element/string.json { “strings”: [ {“name”: “app_name”, “value”: “Weather Assistant”}, {“name”: “welcome”, “value”: “Welcome to Weather Assistant”}, {“name”: “weather_desc”, “value”: “Sunny today, great for outdoor activities”}, {“name”: “switch_lang”, “value”: “Switch to Chinese”} ] }
• 在 ArkUI 中通过 $r(‘app.string.xxx’) 引用资源，所有 UI 组件（如 Text、Button、Image 的 accessibilityDescription 等）均可直接使用该方式实现文本本地化。

二 在UI中使用多语言资源

• 直接在组件属性中使用资源引用，切换系统语言后，界面会自动加载对应语言的字符串资源，无需修改组件代码。 @Entry @Component struct Index { build() { Column({ space: 10 }) { Text($r(‘app.string.welcome’)) Text($r(‘app.string.weather_desc’)) Button($r(‘app.string.switch_lang’)) .onClick(() => { // 语言切换逻辑见下一节 }) } .padding(10) .width(‘100%’) .height(‘100%’) } }
• 对于非文本资源（如图片、动画），可按语言在 resources/zh/media、resources/en/media 下分别放置同名资源，运行时通过资源管理接口加载对应语言的资源路径。

三 运行时语言切换

• 方案A 跟随系统语言

  • 使用 @ohos.i18n 获取或设置系统语言，系统会自动选择匹配的资源包，UI 组件会自动刷新显示。 import i18n from ‘@ohos.i18n’;

    // 获取系统语言，例如：zh-Hans-CN const lang = i18n.getSystemLanguage();

    // 切换系统语言（需要系统权限，常见为 system_basic） i18n.setSystemLanguage(‘en’); // 或 ‘zh’

  • 注意：setSystemLanguage 通常要求系统级权限，适合系统应用或特定场景；普通应用更推荐方案B。

• 方案B 应用内语言（推荐）
  • 将用户选择的语言持久化（如 Preferences），在应用启动时读取并作为“应用语言”使用；所有页面通过 $r(‘app.string.xxx’) 读取，由于资源包已按语言准备，UI 会直接呈现对应语言。
  • 可选优化：将当前语言存入 AppStorage 并在根组件监听变化，触发页面重建或局部刷新，提升切换体验。 // 伪代码示例 // 启动时：读取持久化语言 -> AppStorage.setOrCreate(‘currentLang’, lang) // 切换时：持久化新语言 -> AppStorage.set(‘currentLang’, newLang) -> 触发UI更新
  • 该方案无需系统权限，适配面广，易于测试与维护。

四 进阶格式化与系统能力

• 日期、数字、复数等格式化建议使用 @ohos.intl，避免手动拼接，保证不同区域显示一致。 import intl from ‘@ohos.intl’;

  const date = new Date(2022, 5, 1, 17, 45, 30); const fmtEn = new intl.DateTimeFormat(‘en-GB’); console.log(fmtEn.format(date)); // 01/06/2022

  const fmtZh = new intl.DateTimeFormat(‘zh-CN’); console.log(fmtZh.format(date)); // 2022/6/1

• OpenHarmony 的 全球化子系统 提供资源管理与国际化底层能力（字符串、媒体资源加载解析，时间日期/数字/电话/复数等格式化），UI 组件的多语言能力建立在该子系统之上。

五 常见问题与最佳实践

• 资源覆盖与回退：始终提供 base 作为默认资源，新增语言只覆盖需要翻译的条目，减少维护成本。
• 权限与边界：仅当需要全局改变设备语言时才调用 i18n.setSystemLanguage；普通应用优先采用“应用内语言”方案。
• 切换体验：语言变更后，使用 AppStorage 驱动页面重建或局部刷新，避免直接操作 DOM/组件内部状态。
• 布局适配：不同语言文本长度差异较大，预留宽度与行高，必要时为关键界面做伪本地化测试（极长/极短文本）。
• 测试覆盖：至少覆盖 zh / en 两种语言，并验证系统语言切换与应用内切换两条路径；涉及数字/日期的页面用 intl 统一格式化。