前言

你的 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'

function changeToEnglish() {
  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
@Component
struct 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。现在就回去扫一遍你的项目，把硬编码文案搬进资源文件。