H5 国际化、数字与时区处理

国际化不只是把中文替换成英文。文本长度、复数规则、数字分组、货币、小数位、日期顺序和阅读方向都会变化。尤其是时间，如果把服务端时间、用户时区和显示字符串混在一起，很容易出现跨日和夏令时错误。

一、文案使用稳定语义键

业务代码不应把完整中文句子作为翻译键。稳定键能够在文案调整后保持引用不变。

type MessageKey =
  | 'order.submit'
  | 'order.cancel'
  | 'order.status.pending';

function translate(
  key: MessageKey,
  parameters: Record<string, string | number> = {}
): string {
  return messageCatalog.format(key, parameters);
}

翻译函数和词库加载使用项目现有国际化体系，不在组件中自行拼接语言文件。

二、不要拼接句子片段

不同语言的词序不同。把“共”“条记录”与数字拼接，翻译后可能无法调整顺序。

应把完整句子作为一个消息模板，并把数量作为参数。参数名称表达语义，而不是依赖位置。

三、正确处理复数

复数规则并非只有单数和复数两种，语言之间差异很大。使用项目国际化组件或 Intl.PluralRules 选择消息分支。

function itemCountMessage(count: number, locale: string): string {
  const category = new Intl.PluralRules(locale).select(count);
  return messageCatalog.format(`item.count.${category}`, { count });
}

词库应包含目标语言实际需要的类别，不能只以英语规则推断所有语言。

四、数字交给本地化格式器

function formatNumber(value: number, locale: string): string {
  return new Intl.NumberFormat(locale, {
    maximumFractionDigits: 2
  }).format(value);
}

分组符号和小数符号会随地区变化。用户输入解析不能简单删除逗号，因为它在某些地区可能是小数分隔符。金额输入应使用项目统一解析规则，并在提交前转换为精确业务单位。

五、货币包含币种语义

货币格式需要明确币种和小数规则，不能只在数字前拼一个符号。同一符号可能代表不同币种，显示关键金额时应根据产品要求提供足够上下文。

function formatCurrency(
  amount: number,
  currency: string,
  locale: string
): string {
  return new Intl.NumberFormat(locale, {
    style: 'currency',
    currency
  }).format(amount);
}

精确金额计算仍应使用整数最小单位或项目十进制方案，格式器只负责展示。

六、时间存储与显示分离

系统内部保存统一时间点，显示时才转换为用户或业务时区。不要把已经格式化的本地时间字符串当作可计算时间。

function formatOrderTime(
  instant: Date,
  locale: string,
  timeZone: string
): string {
  return new Intl.DateTimeFormat(locale, {
    dateStyle: 'medium',
    timeStyle: 'short',
    timeZone
  }).format(instant);
}

服务端协议应明确时间是否包含时区或偏移，客户端不能根据字符串外观猜测。

七、区分用户时区与业务时区

日程提醒通常跟随用户时区，交易日和活动截止时间可能使用固定业务时区。用户旅行后，两者行为不同。

页面文案应在可能误解时标明时区。倒计时以目标时间点计算，不依赖本地格式化后的日期文本。

八、处理从右向左布局

布局使用逻辑方向属性，而不是固定左和右：

.summary-card {
  padding-inline: 16px;
  margin-inline-start: 12px;
  text-align: start;
}

带方向含义的箭头需要镜像，播放、勾选等无方向图标通常不应镜像。数字与文本混排还要检查双向文本顺序。

九、为文本膨胀留空间

翻译后文案可能明显变长。按钮和标签不要依赖固定文字宽度，关键操作不能因为省略号失去含义。

测试应使用最长语言、连续数字和窄屏。必要时让按钮换行、调整排列或采用更简洁文案，而不是缩小到难以阅读。

十、语言切换与缓存

语言变化后，页面文案、日期、数字和缓存的展示模型都需要更新。缓存应保存原始业务值，不保存只适用于某种语言的最终字符串。

词库异步加载期间显示稳定状态，避免先闪现另一语言。新增语言能力要符合最低浏览器兼容范围，不支持的格式化功能使用项目现有兼容层。

十一、建立测试矩阵

• 不同语言的复数分支。
• 小数和分组符号差异。
• 多币种与负金额。
• 跨日、跨年和夏令时切换。
• 用户时区变化后的提醒。
• 从右向左布局和混排文本。
• 最长文案下的按钮与表格。

总结

国际化需要把语义、数值和显示分开。完整句子使用稳定键和参数，复数、数字与货币交给本地化格式器，时间点保存为统一值并在明确时区下展示。配合逻辑方向布局和长文本测试，H5 才能真正适应不同语言与地区。