HarmonyOS7 资源管理与国际化：多语言适配配置

文章目录

• • 前言
  • 资源目录结构
  • • 代码实现
  • 在 string.json 里定义文案
  • 代码里引用：用 $r
  • 动态切换语言
  • • 核心代码
  • 图片/布局也能分语言
  • 常见坑
  • 常见误区（小白必踩）
  • 完整可运行示例：多语言适配
  • • 完整示例
    • 代码解析
  • 写在最后

前言

你的 app 想卖到海外，或者只是想支持"简体/繁体"切换，就得做国际化（i18n）。HarmonyOS 的资源管理体系把这件事变得很规范。

核心思路一句话：别把文字写死在代码里，全放进资源文件，按语言分目录。这篇文章我把资源配置、多语言切换、以及常见陷阱讲清。

资源目录结构

HarmonyOS 用resources/下的base（默认）和带限定词（如zh_CN、en_US）的目录来区分语言：

代码实现

resources/ ├── base/element/string.json # 默认（兜底）文案 ├── zh_CN/element/string.json # 简体中文 └── en_US/element/string.json # 英文

系统会根据设备语言自动选对应目录。找不到才用base兜底。

在 string.json 里定义文案

// base/element/string.json{"string":[{"name":"hello","value":"Hello"},{"name":"login","value":"Login"}]}// zh_CN/element/string.json{"string":[{"name":"hello","value":"你好"},{"name":"login","value":"登录"}]}

每个文案用name作键，不同语言目录里name一致、value不同。

代码里引用：用 $r

Text($r('app.string.hello'))// 自动按当前语言取对应文案Button($r('app.string.login'))

• $r('app.string.xxx')：引用string.json里name=xxx的值。
• 不要在代码里写Text('你好')这种字面值，否则切换语言它不会变。

动态切换语言

用户想手动切语言（而不依赖系统），需要改配置并重启资源上下文：

核心代码

import{i18n}from'@kit.LocalizationKit'functionchangeToEnglish(){i18n.setAppPreferredLanguage('en')// 设为英文// 通常还需重新加载页面或重启 Ability 让资源生效}

• i18n.setAppPreferredLanguage('en')：设置 app 偏好语言。
• 切换后建议引导用户重启 app 或重新加载当前页，资源才会刷新。

图片/布局也能分语言

不止文字，连图片、布局都能按语言分目录：在zh_CN/media/、en_US/media/放同名不同图，引用时一样用$r('app.media.logo')，系统自动选。

常见坑

坑	现象	解决
文案写死在代码	切换语言不变	一律用$r引用
name 拼写不一致	取不到报找不到	多语言目录 name 必须一致
忘了 base 兜底	某种语言缺字段崩	base 放完整默认文案
切换不生效	资源没重载	切换后重启上下文

常见误区（小白必踩）

误区	说明
文案写死在代码	Text('你好')切换语言不变，必须一律用$r('app.string.xxx')引用。
多语言name不一致	不同语言目录里name要对齐，否则取不到报找不到。
忘了base兜底	某种语言缺字段直接崩，base 放完整默认文案。
切换不重载	动态切语言后记得重启上下文让资源刷新。

下面这段代码可以直接复制到 DevEco Studio 里运行。建议你边读边敲，改一改文末「动手改一改」里的参数，亲眼看看效果。

完整可运行示例：多语言适配

用Resource引用字符串，切换系统语言自动变。

完整示例

// 资源引用：中文/英文各一份，系统语言自动选@Entry@Componentstruct I18nDemo{build(){Column({space:16}){// $r 会按系统语言取对应资源Text($r('app.string.hello'))Text($r('app.string.welcome'))}.padding(20)}}

配套资源（resources/base/element/string.json 与 resources/en_US/element/string.json）：

代码解析

{"string":[{"name":"hello","value":"你好"}]}// 中文{"string":[{"name":"hello","value":"Hello"}]}// 英文

你会看到什么：系统切到英文时，界面文字自动变成Hello，无需改代码——所有文案都走$r('app.string.xxx')资源引用。

动手改一改：

• 新增zh_TW资源目录，体验繁体适配。
• 用$plurals处理「1 条消息 / 3 条消息」复数。
• 用ResourceManager在 JS 逻辑里取字符串（不止 UI）。

写在最后

国际化三步走：文案进 string.json（不写死）、按语言分目录、代码用$r引用。图片、布局同理可分目录。再配合i18n动态切换，多语言就齐活了。

记住一条铁律：代码里出现任何用户可见的中文字符串，都是国际化的 bug。现在就回去扫一遍你的项目，把硬编码文案搬进资源文件。