一、原理解析

鸿蒙 6 的国际化基于「资源文件目录分级」和「系统语言检测」，核心机制：

1. 资源文件按语言 / 区域划分目录（如en/ja对应英文 / 日语），系统自动根据当前语言加载对应资源；
2. 字符串国际化通过$r('app.string.xxx')引用，图片国际化通过$r('app.media.xxx')引用；
3. 动态切换语言需通过resourceManager手动指定语言，并重载页面资源。

二、完整实现步骤

步骤 1：配置国际化资源文件

1. 目录结构（重点）

src/main/resources/
├── base/                  // 默认资源（中文）
│   ├── element/
│   │   └── string.json    // 中文字符串
│   └── media/             // 中文图片资源
│       ├── logo.png
│       └── background.png
├── en/                    // 英文资源
│   ├── element/
│   │   └── string.json    // 英文字符串
│   └── media/             // 英文图片资源
│       ├── logo.png
│       └── background.png
└── ja/                    // 日语资源
    ├── element/
    │   └── string.json    // 日语字符串
    └── media/             // 日语图片资源
        ├── logo.png
        └── background.png

2. 字符串资源文件示例

• base/element/string.json（中文）：

  {
    "string": [
      { "name": "app_name", "value": "鸿蒙国际化示例" },
      { "name": "login_btn", "value": "登录" },
      { "name": "welcome_msg", "value": "欢迎使用本应用" },
      { "name": "date_format", "value": "yyyy年MM月dd日" }
    ]
  }
  

• en/element/string.json（英文）：

  {
    "string": [
      { "name": "app_name", "value": "HarmonyOS I18N Demo" },
      { "name": "login_btn", "value": "Login" },
      { "name": "welcome_msg", "value": "Welcome to the app" },
      { "name": "date_format", "value": "MM/dd/yyyy" }
    ]
  }
  

• ja/element/string.json（日语）：

  {
    "string": [
      { "name": "app_name", "value": "ハーモニーOS国際化デモ" },
      { "name": "login_btn", "value": "ログイン" },
      { "name": "welcome_msg", "value": "アプリへようこそ" },
      { "name": "date_format", "value": "yyyy年MM月dd日" }
    ]
  }
  

步骤 2：组件中使用国际化资源

import resourceManager from '@ohos.resourceManager';
import common from '@ohos.app.ability.common';
import router from '@ohos.router';
import { BusinessError } from '@ohos.base';

@Entry
@Component
struct I18NDemo {
  private context = getContext(this) as common.UIAbilityContext;
  @State currentLanguage: string = 'zh'; // 当前语言：zh/en/ja
  @State currentDate: string = '';

  build() {
    Column({ space: 30 })
      .width('100%')
      .height('100%')
      .padding(20)
      .justifyContent(FlexAlign.Center) {
      // 国际化图片
      Image($r('app.media.logo'))
        .width(100)
        .height(100)

      // 国际化字符串
      Text($r('app.string.welcome_msg'))
        .fontSize(20)

      Text(this.currentDate)
        .fontSize(16)

      // 语言切换按钮
      Flex({ space: 10, justifyContent: FlexAlign.Center }) {
        Button('中文')
          .onClick(() => this.switchLanguage('zh'))
          .backgroundColor(this.currentLanguage === 'zh' ? '#54A0FF' : '#CCCCCC')
        Button('English')
          .onClick(() => this.switchLanguage('en'))
          .backgroundColor(this.currentLanguage === 'en' ? '#54A0FF' : '#CCCCCC')
        Button('日本語')
          .onClick(() => this.switchLanguage('ja'))
          .backgroundColor(this.currentLanguage === 'ja' ? '#54A0FF' : '#CCCCCC')
      }

      Button($r('app.string.login_btn'))
        .width('80%')
    }
  }

  // 切换语言
  private async switchLanguage(lang: string) {
    this.currentLanguage = lang;
    // 1. 设置资源管理器的语言
    const rm = this.context.resourceManager;
    await rm.setPreferredLanguage([lang]);
    // 2. 重新加载页面资源（通过状态更新触发）
    this.updateDate();
  }

  // 格式化日期（区域适配）
  private updateDate() {
    const date = new Date();
    const format = $r('app.string.date_format').value;
    this.currentDate = format.replace('yyyy', date.getFullYear().toString())
      .replace('MM', (date.getMonth() + 1).toString().padStart(2, '0'))
      .replace('dd', date.getDate().toString().padStart(2, '0'));
  }

  aboutToAppear() {
    // 页面加载时获取系统当前语言
    this.getCurrentSystemLanguage();
    this.updateDate();
  }

  // 获取系统当前语言
  private async getCurrentSystemLanguage() {
    const rm = this.context.resourceManager;
    const langs = await rm.getPreferredLanguage();
    this.currentLanguage = langs[0] || 'zh';
  }
}

步骤 3：配置 module.json5（声明支持的语言）

{
  "module": {
    "name": "entry",
    "type": "entry",
    "compileSdkVersion": 20,
    "targetSdkVersion": 20,
    "minSdkVersion": 20,
    "supportedLanguages": ["zh", "en", "ja"], // 声明支持的语言
    "abilities": [
      // 能力配置...
    ]
  }
}

三、避坑点

1. 资源目录命名规范：语言目录必须使用 ISO 639-1 标准缩写（如en/ja），区域目录用en_US/zh_CN格式；
2. 资源引用方式：必须用$r('app.xxx.xxx')引用，不可硬编码字符串 / 图片路径；
3. 动态切换生效：切换语言后需通过状态更新触发组件重绘，或调用router.replaceUrl重载页面；
4. 图片资源一致性：不同语言目录下的图片文件名必须一致，否则会导致加载失败；
5. 系统语言适配：应用未声明的语言，系统会自动 fallback 到base目录的默认资源。