HarmonyOS 鸿蒙Next中APP如何实现多语言切换（中文/英文），支持自动适配系统语言？

HarmonyOS 鸿蒙Next中APP如何实现多语言切换（中文/英文），支持自动适配系统语言？

问题描述

开发的鸿蒙 APP 需要面向国内外用户，需支持中文和英文切换，包括界面文字、提示语等，如何配置多语言资源文件？如何实现手动切换语言并实时生效？是否能自动适配系统语言？关键字：鸿蒙多语言、资源配置、语言切换、系统语言适配、实时生效

回答内容

原理解析

鸿蒙的多语言适配基于 “资源目录分级” 机制：

• 在resources目录下按语言类型创建子目录（如en对应英文、zh对应中文）；
• 系统会根据设备语言自动加载对应目录的资源文件；
• 手动切换语言需通过Configuration修改应用语言配置，并重载 UI 实现实时生效。

实现步骤

步骤 1：配置多语言资源文件

1. 项目资源目录结构：

src/main/resources/
├── base/                  // 默认资源（中文）
│   └── element/
│       └── string.json    // 中文文案
├── en/                    // 英文资源
│   └── element/
│       └── string.json    // 英文文案
└── zh/                    // 中文资源（可选，与base一致时可省略）
    └── element/
        └── string.json

1. 中文资源（base/element/string.json）：

{
  "app_name": "我的应用",
  "login_btn": "登录",
  "welcome_msg": "欢迎使用本应用",
  "setting_language": "语言设置"
}

1. 英文资源（en/element/string.json）：

{
  "app_name": "My App",
  "login_btn": "Login",
  "welcome_msg": "Welcome to the app",
  "setting_language": "Language Setting"
}

步骤 2：自动适配系统语言

无需额外代码，鸿蒙会自动根据设备系统语言加载对应资源：

• 系统语言为中文→加载base或zh目录资源；
• 系统语言为英文→加载en目录资源；
• 若系统语言无对应资源目录→加载base目录默认资源。

步骤 3：手动切换语言并实时生效

import common from '@ohos.app.ability.common';
import window from '@ohos.window';
import resourceManager from '@ohos.resourceManager';

class LanguageManager {
  private context = getContext(this) as common.UIAbilityContext;

  // 切换语言（参数：zh-CN=中文，en-US=英文）
  async switchLanguage(lang: string) {
    try {
      // 1. 获取应用配置
      const config = this.context.config;
      config.language = lang; // 设置语言

      // 2. 更新应用配置
      await this.context.updateConfiguration(config);

      // 3. 重新加载资源管理器
      const resMgr = await resourceManager.getResourceManager(this.context.bundleCodeDir, lang);
      this.context.resourceManager = resMgr;

      // 4. 刷新当前页面（实时生效）
      const win = await window.getLastWindow(this.context);
      await win.restart(); // 重启窗口，重载UI
      console.log('语言切换为：', lang);
    } catch (err) {
      console.error('语言切换失败：', err);
    }
  }
}

步骤 4：在 UI 中使用多语言文案

@Entry
@Component
struct LanguageDemo {
  private languageManager = new LanguageManager();
  @State currentLang: string = 'zh-CN';

  build() {
    Column({ space: 20 }) {
      // 使用多语言文案（$r('app.string.xxx')引用资源）
      Text($r('app.string.welcome_msg'))
        .fontSize(20)
      
      Button($r('app.string.login_btn'))
        .width('50%')
      
      // 语言切换按钮
      Button($r('app.string.setting_language'))
        .onClick(async () => {
          // 切换为英文（再次点击可切换回中文）
          const targetLang = this.currentLang === 'zh-CN' ? 'en-US' : 'zh-CN';
          await this.languageManager.switchLanguage(targetLang);
          this.currentLang = targetLang;
        })
    }
    .width('100%')
    .height('100%')
    .justifyContent(FlexAlign.Center)
  }
}

步骤 5：获取当前系统语言

// 获取系统当前语言
async getSystemLanguage() {
  const context = getContext(this) as common.UIAbilityContext;
  const config = context.config;
  console.log('当前系统语言：', config.language); // 输出如zh-CN、en-US
  return config.language;
}

避坑提醒

• 资源文件命名必须为string.json，目录结构需严格遵循语言目录/element/格式；
• 引用文案必须使用$r('app.string.xxx')（而非硬编码），否则无法适配多语言；
• 手动切换语言后需重启窗口或页面，才能让所有文案生效；
• 支持的语言代码需符合 ISO 标准（如中文zh-CN、英文en-US、日语ja-JP）。