在全球化应用开发中，​​多语言本地化（i18n）​​是让应用适配不同国家/地区语言的核心能力。鸿蒙（HarmonyOS）通过“资源分组+系统语言感知”的设计，让开发者能高效实现“应用自动跟随系统语言切换”的功能。本文将以​​ArkTS语言​​为例，带新手从0到1实现多语言适配，涵盖资源创建、自动识别、动态切换全流程。

---

一、为什么需要多语言本地化？

当应用面向全球用户时，不同地区的用户使用习惯差异巨大：

• 中文用户需要“确认”按钮显示为“确定”；
• 英语用户需要“Cancel”而非“取消”；
• 阿拉伯语用户需要从右到左（RTL）的布局。

鸿蒙的多语言本地化机制能让应用​​自动根据系统语言环境加载对应资源​​，无需手动干预，大幅提升用户体验。

---

二、鸿蒙多语言本地化的核心机制

1. 资源分组（Resource Groups）

鸿蒙将应用资源（字符串、图片、布局等）按“语言+地区”分组存储，系统会根据当前设备的语言设置自动选择匹配的资源组。
​​资源文件命名规则​​：resources/base/（基础资源） + media/（图片） + string/（文本） + [语言代码]-[地区代码]/（如en-US、zh-CN）。

2. 语言优先级

系统按以下顺序匹配语言资源：

1. 设备系统语言（如zh-CN）；
2. 系统语言的区域变体（如zh-Hans简体中文）；
3. 默认语言（应用指定的fallback语言，通常为en-US）。

3. 关键API：@ohos.i18n

鸿蒙提供i18n模块用于获取当前语言环境、格式化日期/数字等，核心类包括：

• Locale：表示语言区域（如new Locale('zh', 'CN')）；
• Resource：管理资源文件的加载与解析。

---

三、实战：实现“系统语言自动切换”

步骤1：创建多语言资源文件

在项目的resources目录下，按语言创建资源分组。以“欢迎语”和“按钮文本”为例：

（1）基础资源（默认语言，如英文）

路径：resources/base/string/en-US.json

{
  "welcome": "Welcome to My App!",
  "button_submit": "Submit",
  "button_cancel": "Cancel"
}

（2）中文（简体）资源

路径：resources/base/string/zh-CN.json

{
  "welcome": "欢迎使用我的应用！",
  "button_submit": "提交",
  "button_cancel": "取消"
}

（3）阿拉伯语（右到左布局）资源

路径：resources/base/string/ar-SA.json

{
  "welcome": "مرحبًا بك في تطبيقي!",
  "button_submit": "إرسال",
  "button_cancel": "إلغاء"
}

---

步骤2：在界面中引用多语言资源

鸿蒙支持通过$r语法直接引用资源文件中的字符串，界面会自动根据当前语言环境加载对应内容。

// 页面结构（ets文件）
@Entry
@Component
struct LocalizedDemoPage {
  build() {
    Column() {
      // 引用字符串资源（自动匹配系统语言）
      Text($r('app.string.welcome'))
        .fontSize(24)
        .fontWeight(FontWeight.Bold)
        .margin(20)
      
      // 按钮文本也通过资源引用
      Button($r('app.string.button_submit'))
        .width('40%')
        .height(50)
        .margin(10)
      
      Button($r('app.string.button_cancel'))
        .width('40%')
        .height(50)
        .margin(10)
    }
    .width('100%')
    .height('100%')
  }
}

​​注意​​：资源路径前缀app.string对应resources/base/string/目录（app是默认包名，可通过build-profile.json5修改）。

---

步骤3：动态获取当前语言环境（可选）

如果需要在代码中判断当前语言（如统计用户语言偏好），可通过Locale类获取：

import i18n from '@ohos.i18n';

// 获取当前系统语言环境（返回Locale对象）
const currentLocale = i18n.getLocale();
console.info(`当前语言：${currentLocale.language}, 地区：${currentLocale.region}`);

// 示例：根据语言显示提示
if (currentLocale.language === 'zh') {
  console.info('用户使用中文');
} else if (currentLocale.language === 'en') {
  console.info('用户使用英文');
}

---

步骤4：实现“手动切换语言”（进阶）

鸿蒙默认自动跟随系统语言，但部分应用需要支持用户手动切换（如设置页选择语言）。此时需手动更新应用语言环境，并重启界面。

（1）添加语言切换逻辑

import i18n from '@ohos.i18n';
import common from '@ohos.app.ability.common';

@Entry
@Component
struct LocalizedDemoPage {
  // 存储当前选择的语言（默认跟随系统）
  @State currentLang: string = i18n.getLocale().language;

  // 手动切换语言的方法
  switchLanguage(lang: string) {
    // 设置应用语言（需重启页面生效）
    i18n.setLocale(new Locale(lang, ''));
    // 重启当前页面（触发资源重新加载）
    router.back();  // 先返回上一页
    setTimeout(() => {
      router.pushUrl({ url: 'pages/LocalizedDemoPage' });  // 重新进入当前页
    }, 100);
  }

  build() {
    Column() {
      // ...（同步骤2的界面代码）

      // 手动切换语言的按钮（示例）
      Row() {
        Button('切换英文')
          .onClick(() => this.switchLanguage('en'))
        Button('切换中文')
          .onClick(() => this.switchLanguage('zh'))
        Button('切换阿拉伯语')
          .onClick(() => this.switchLanguage('ar'))
      }
      .margin(20)
    }
  }
}

（2）注意事项

• 手动切换语言后需​​重启页面​​（或应用），否则资源不会立即更新；
• 部分设备可能需要清除应用缓存才能生效；
• 阿拉伯语等RTL语言需额外处理布局（如flexDirection: FlexDirection.RowReverse）。

---

四、新手常见问题与解决方案

1. 资源文件未生效？

• ​​现象​​：切换语言后界面文本未变化。
• ​​原因​​：资源文件命名错误（如zh-CN.json写成zh_CN.json）或路径错误（需放在resources/base/string/下）。
• ​​解决​​：检查文件路径和命名是否符合[语言]-[地区].json格式。

2. 默认语言不生效？

• ​​现象​​：系统语言不在支持列表中，应用未回退到默认语言（如en-US）。
• ​​原因​​：未在module.json5中声明fallbackLocale。
• ​​解决​​：在module.json5的app配置中添加：

  {
    "app": {
      "fallbackLocale": "en-US"
    }
  }

3. 阿拉伯语布局错乱？

• ​​现象​​：文本从左到右显示，而非从右到左。
• ​​原因​​：未适配RTL语言的布局特性。
• ​​解决​​：在布局中添加layoutDirection: LayoutDirection.RTL（仅阿拉伯语等RTL语言生效）：

  // 在页面build方法中动态设置
  .layoutDirection(this.currentLang === 'ar' ? LayoutDirection.RTL : LayoutDirection.LTR)