一、背景说明

鸿蒙生态终端用户规模正式突破 1 亿,出海多区域分发成为原生应用的新增刚需——同一份数据,在中国显示"¥12,800"、在德国就会因逗号分隔符被误读。本文聚焦一个具体技术点:使用 Localization Kit 的 @ohos.i18n 与 @ohos.intl 两个模块,实现系统区域检测、数字/货币/单位格式化、日期顺序适配的完整国际化方案,全部代码可直接编译运行。

二、技术原理

鸿蒙的国际化能力由两个互补模块组成:

  • @ohos.intl:实现 ECMA 402 标准定义的基础能力——Intl.NumberFormat(数字/货币/单位格式化)、Intl.DateTimeFormat(日期时间格式化)、Intl.Collator(排序)。
  • @ohos.i18n:ECMA 402 之外的增强能力——i18n.System.getSystemRegion() 获取系统区域、I18NUtil.unitConvert() 度量衡换算、I18NUtil.getDateOrder() 获取年月日排列顺序等。

核心数据流:getSystemLanguage/getSystemRegion 读系统设置 → 以区域 ID(如 zh-Hans-CN)构造 Formatter → 数据进 format() → 按当地习惯输出 → 监听 COMMON_EVENT_LOCALE_CHANGED 响应用户切区。

底层基于 CLDR 国际化数据库,输出格式随标准演进可能调整——官方明确要求不要对格式化结果做硬编码解析,只用于展示。

三、实现步骤

工程为 Stage 模型(API 12+),国际化能力无需任何权限,module.json5 保持默认。

1. 区域化格式化工具 I18nFormatter.ets
import { i18n, intl } from '@kit.LocalizationKit';

export class I18nFormatter {
  private static region: string = 'CN';

  // 应用启动时初始化:读取系统语言与区域
  static init(): void {
    const lang = i18n.System.getSystemLanguage(); // 如 'zh-Hans-CN'
    I18nFormatter.region = i18n.System.getSystemRegion(); // 如 'CN'
    console.info(`system lang=${lang}, region=${I18nFormatter.region}`);
  }

  // 数字格式化:1,000 分组分隔符随区域变化
  static formatNumber(num: number): string {
    const formatter = new intl.NumberFormat();
    return formatter.format(num);
  }

  // 货币格式化:传入 ISO-4217 货币代码
  static formatCurrency(amount: number, currency: string): string {
    const formatter = new intl.NumberFormat({
      style: 'currency',
      currency: currency,        // 'CNY' → ¥12,800.00;'EUR' → 12.800,00 €
      currencyDisplay: 'symbol'  // 'code'→CNY / 'narrowSymbol'→¥ / 'name'→人民币
    });
    return formatter.format(amount);
  }

  // 单位格式化:配合 unitUsage 可按场景自动选单位(如文件大小、行驶速度)
  static formatUnit(value: number, unit: string, usage: string = 'default'): string {
    const formatter = new intl.NumberFormat({
      style: 'unit',
      unit: unit,                // 'meter'、'hectare'、'beat-per-minute' 等
      unitUsage: usage,
      unitDisplay: 'short'
    });
    return formatter.format(value);
  }

  // 度量衡换算:美制 cup → 公制 liter,并按目标区域格式化
  static convertUnit(value: number, fromUnit: string, fromSystem: string,
    toUnit: string, toSystem: string, locale: string): string {
    const from: i18n.UnitInfo = { unit: fromUnit, measureSystem: fromSystem };
    const to: i18n.UnitInfo = { unit: toUnit, measureSystem: toSystem };
    return i18n.I18NUtil.unitConvert(from, to, value, locale, 'long');
  }

  // 日期格式化:年月日顺序、时制自动按区域适配
  static formatDate(date: Date, locale: string = 'zh-CN'): string {
    const formatter = new intl.DateTimeFormat(locale, {
      dateStyle: 'medium',
      timeStyle: 'short'
    });
    return formatter.format(date); // zh-CN: 2026年11月16日 20:30;en-US: Nov 16, 2026, 8:30 PM
  }

  // 获取区域日期顺序:'y-L-d'(中国)/ 'M-d-y'(美国)——自定义日期选择器时必须使用
  static getDateOrder(locale: string): string {
    return i18n.I18NUtil.getDateOrder(locale);
  }
}
2. UI 调用示例 Index.ets
import { i18n, intl } from '@kit.LocalizationKit';
import { commonEventManager } from '@kit.BasicServicesKit';
import { I18nFormatter } from '../model/I18nFormatter';

@Entry
@Component
struct Index {
  @State result: string = '';

  build() {
    Column({ space: 12 }) {
      Button('按系统区域格式化').onClick(() => {
        I18nFormatter.init();
        const lines: string[] = [
          `数字:${I18nFormatter.formatNumber(1234567.89)}`,
          `人民币:${I18nFormatter.formatCurrency(12800, 'CNY')}`,
          `欧元:${I18nFormatter.formatCurrency(12800, 'EUR')}`,
          `单位:${I18nFormatter.formatUnit(42, 'kilometer', 'length-road')}`,
          `日期顺序(zh-CN):${I18nFormatter.getDateOrder('zh-CN')}`,
          `日期:${I18nFormatter.formatDate(new Date(), 'zh-CN')}`
        ];
        this.result = lines.join('\n');
      })

      // 出海对照:同一组数据在三个区域的展示差异
      Button('多区域对照').onClick(() => {
        const rows: string[] = ['zh-CN|CNY', 'de-DE|EUR', 'en-US|USD'].map((row: string) => {
          const [locale, currency] = row.split('|');
          const nf = new intl.NumberFormat({ style: 'currency', currency: currency });
          const df = new intl.DateTimeFormat(locale, { dateStyle: 'full' });
          return `${locale}: ${nf.format(12800)} | ${df.format(new Date())}`;
        });
        this.result = rows.join('\n');
      })

      Text(this.result || '点击按钮体验')
        .fontSize(13)
        .width('90%')
        .height(200)
        .backgroundColor('#F2F3F5')
        .padding(12)
        .borderRadius(8)
    }
    .width('100%')
    .height('100%')
    .justifyContent(FlexAlign.Center)
  }
}
3. 监听用户切换系统区域

用户切区后格式化结果需要即时刷新,订阅系统公共事件即可:

import { commonEventManager } from '@kit.BasicServicesKit';
import { BusinessError } from '@kit.BasicServicesKit';

let subscriber: commonEventManager.CommonEventSubscriber | null = null;
commonEventManager.createSubscriber({
  events: ['usual.event.LOCALE_CHANGED']
}, (err: BusinessError, data: commonEventManager.CommonEventSubscriber) => {
  subscriber = data;
  subscriber.on('onCommonEvent', () => {
    I18nFormatter.init();      // 重读系统区域
    this.refreshAllFormatters(); // 重建各处 Formatter 并刷新 UI
  });
});
四、应用场景示例

跨境电商订单页:金额、运费(含度量衡换算)、下单时间一并按买家区域渲染:

import { i18n, intl } from '@kit.LocalizationKit';

function renderOrder(amount: number, weightGram: number, locale: string, currency: string): string {
  const currencyText = new intl.NumberFormat({
    style: 'currency', currency: currency
  }).format(amount);
  // 500g 按目标区域习惯换算展示(英制显示盎司,公制显示千克)
  const weightText = i18n.I18NUtil.unitConvert(
    { unit: 'gram', measureSystem: 'SI' },
    locale === 'en-US' ? { unit: 'ounce', measureSystem: 'US' } : { unit: 'kilogram', measureSystem: 'SI' },
    weightGram, locale, 'short');
  const dateText = new intl.DateTimeFormat(locale, { dateStyle: 'medium' }).format(new Date());
  return `${currencyText} | ${weightText} | ${dateText}`;
}
// renderOrder(12800, 500, 'en-US', 'USD') → "$12,800.00 | 17.637 oz | Nov 16, 2026"
五、技术要点
1. 区域 ID 的规范

locale 由"语言-脚本-地区"组成(zh-Hans-CN),传入非法 ID 时 Formatter 会按 best fit 策略回退到最近匹配区域——结果可能不符合预期,建议始终基于 i18n.System.getSystemLanguage() 的返回值构造,不要硬编码。

2. CLDR 数据版本

格式化输出基于 CLDR 数据库,随系统版本演进可能调整(API 12 对应 CLDR 42)。官方明确:返回值仅用于界面展示,禁止对其做正则解析或相等性判断做业务逻辑,否则系统升级后行为可能变化。

3. 错误处理
try {
  const nf = new intl.NumberFormat({ style: 'currency', currency: 'CNY' });
} catch (err) {
  const e = err as BusinessError;
  if (e.code === 401) {
    console.error('区域 ID 非法或 options 参数错误');
  } else {
    console.error(`i18n error code=${e.code}`);
  }
}
4. 使用限制
  • DateTimeFormat(旧类名)自 API 20 起废弃,统一使用 Intl.DateTimeFormat;
  • Date 构造的月份从 0 开始计数(0 表示一月),传 1 会得到二月;
  • 部分接口自 API 11 起支持在 ArkTS 卡片中使用,桌面卡片内可直接格式化展示。
六、扩展建议
  1. 文本排序:用 Intl.Collator 按区域规则对商品名排序——拼音序、笔画序由 locale 决定:
const collator = new intl.Collator('zh-Hans-CN');
const sorted = names.sort((a: string, b: string) => collator.compare(a, b)); // 拼音升序
  1. 时区感知:Intl.DateTimeFormat 配合 timeZone 选项展示目的地时间,机票、酒店类应用必备;
  2. 字体管理:API 26.0.1 起 Localization Kit 新增第三方字体安装/卸载能力,可为不同语言市场动态加载专属字体。
结语

本文用 @ohos.i18n 与 @ohos.intl 完成了鸿蒙应用从系统区域检测、数字/货币/单位格式化、日期顺序适配到区域切换监听的完整国际化实现,核心代码约 150 行,均可直接编译运行。掌握 Formatter 的选项体系与区域 ID 规范后,应用出海只需准备翻译文本,数字、金额、日期的本地化呈现交给系统即可。

Logo

openEuler 是由开放原子开源基金会孵化的全场景开源操作系统项目,面向数字基础设施四大核心场景(服务器、云计算、边缘计算、嵌入式),全面支持 ARM、x86、RISC-V、loongArch、PowerPC、SW-64 等多样性计算架构

更多推荐