背景：从中国香港走向世界的技术挑战
Tappo最初是为中国香港市场设计的POS系统，界面全是粤语，数据模型也深度绑定中国香港的餐饮习惯（茶餐厅的「冻柠茶走甜」这种复杂选项是普通POS无法处理的）。
当我们决定出海时，技术团队面临的第一个挑战就是：如何让一个深度本地化的系统支持多语言、多货币、多税制？
国际化 ≠ 翻译
很多开发者认为国际化（i18n）就是把文字翻译成不同语言。实际上，真正的i18n包含四个层次：
| 层次 | 内容 | 难度 |
|---|---|---|
| L1 文字翻译 | UI文案多语言 | ⭐ |
| L2 格式适配 | 日期、货币、数字、时区 | ⭐⭐ |
| L3 布局适配 | RTL（阿拉伯语）、文字长度差异 | ⭐⭐⭐ |
| L4 业务逻辑 | 税率、支付、法规 | ⭐⭐⭐⭐⭐ |
大多数SaaS产品只做到L1，但餐饮SaaS必须做到L4才能在海外市场真正可用。
我们的i18n架构设计
选型：为什么选 react-i18next
评估了市面上的i18n方案后，我们选择了 react-i18next：
| 方案 | 优点 | 缺点 |
|---|---|---|
| react-intl | 生态成熟 | Bundle 体积大 |
| lingui | 编译时优化 | 生态较小 |
| react-i18next | 轻量、插件丰富、社区活跃 | 配置稍复杂 |
翻译文件结构
src/
locales/
zh-HK/ ← 中国香港繁体（原始语言）
common.json
pos.json
menu.json
report.json
zh-CN/ ← 简体中文
en/ ← 英文
th/ ← 泰文
id/ ← 印尼文
vi/ ← 越南文
ms/ ← 马来文
ja/ ← 日文
ko/ ← 韩文
ar/ ← 阿拉伯文（RTL）按功能模块拆分翻译文件的好处是：翻译人员可以并行工作，不会互相阻塞。
动态语言切换
// 核心实现：无需刷新页面的语言切换
import i18n from 'i18next';
import { initReactI18next } from 'react-i18next';
i18n.use(initReactI18next).init({
resources: {
en: { common: enCommon, pos: enPos },
'zh-HK': { common: zhHkCommon, pos: zhHkPos },
// ...
},
lng: 'zh-HK', // 默认语言
fallbackLng: 'en', // 找不到翻译时回退到英文
interpolation: {
escapeValue: false, // React 已经处理 XSS
},
});重点是 fallbackLng: 'en'——当某个翻译key在某些语言中缺失时，自动回退到英文，保证界面不会出现空白。
RTL布局：阿拉伯语的坑
中东市场对餐饮SaaS来说极具吸引力（高ARPU、数字化需求强），但阿拉伯语的从右到左（RTL）布局是一个技术难题。
我们的解决方案：
- CSS Logical Properties：使用
margin-inline-start替代margin-left - Tailwind RTL 插件：自动翻转方向性样式
- 独立RTL测试环境：每个PR必须通过RTL视觉测试
/* ❌ 不要这样写 */
.sidebar { margin-left: 16px; }
/* ✅ 用 Logical Properties */
.sidebar { margin-inline-start: 16px; }翻译管理流程
我们搭建了一套翻译管理流水线：
1. 开发者在 zh-HK.json 中新增 key
2. CI 自动将新 key 推到 Lokalise (翻译管理平台)
3. 翻译团队在 Lokalise 完成翻译
4. CI 自动拉取翻译结果，生成 PR
5. 审核合并后自动部署这套流程解决了「开发等翻译、翻译等开发」的死循环。
本地化测试策略
除了自动化测试，我们还建立了人工测试清单：
- 所有UI文字在目标语言中显示正确（无乱码）
- 日期格式符合当地习惯（如美国 MM/DD/YYYY vs 欧洲 DD/MM/YYYY）
- 货币符号和格式正确（¥100 vs US$100 vs ฿100）
- RTL语言（阿拉伯语）布局正常
- 长文字（德语通常比英文长30%）不会撑爆UI
- 数字格式（千位分隔符、小数点）正确
经验教训
- 越早做i18n越好：如果一开始就设计好i18n架构，后期改造的成本是初期的10倍以上
- 不要用Google翻译做产品翻译：餐饮行业有很多专业术语，必须由懂餐饮的翻译人员处理
- 翻译key要有上下文：
"submit"在不同场景可能是「提交」、「送出」、「确定」，key命名要体现上下文 - RTL比想像中难：不是简单的左右翻转，很多UI组件需要重新设计
结论
国际化改造是餐饮SaaS出海的技术地基。地基没打好，再好的市场策略也无法落地。我们的经验是：用3个月的技术投入，换取11个市场的准入资格，这是一笔非常划算的投资。
相关文章
- 从中国香港茶餐厅到海外市场：POS系统的产品设计差异 — 全球化产品架构设计与可配置UI的实践思路
- 餐饮SaaS出海的全球市场图景 — 为什么国际化是餐饮SaaS出海的第一步
- 出海第一站：为什么选择东南亚 — 多语言产品在东南亚市场的落地实战
阿公寄语：写code𠮶阵唔好谂住净系俾中国香港人用。你永远唔知你嘅产品将来会去到边个国家。由day one就做好国际化架构。
