餐飲SaaS國際化改造實戰：從粵語到支持11種語言

背景：從中國香港走向世界的技術挑戰

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）佈局是一個技術難題。

我們的解決方案：

1. CSS Logical Properties：使用 margin-inline-start 替代 margin-left
2. Tailwind RTL 插件：自動翻轉方向性樣式
3. 獨立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
• 數字格式（千位分隔符、小數點）正確

經驗教訓

1. 越早做i18n越好：如果一開始就設計好i18n架構，後期改造的成本是初期的10倍以上
2. 不要用Google翻譯做產品翻譯：餐飲行業有很多專業術語，必須由懂餐飲的翻譯人員處理
3. 翻譯key要有上下文："submit" 在不同場景可能是「提交」、「送出」、「確定」，key命名要體現上下文
4. RTL比想像中難：不是簡單的左右翻轉，很多UI組件需要重新設計

結論

國際化改造是餐飲SaaS出海的技術地基。地基沒打好，再好的市場策略也無法落地。我們的經驗是：用3個月的技術投入，換取11個市場的准入資格，這是一筆非常划算的投資。

相關文章

• 從中國香港茶餐廳到海外市場：POS系統的產品設計差異 — 全球化產品架構設計與可配置UI的實踐思路
• 餐飲SaaS出海的全球市場圖景 — 為什麼國際化是餐飲SaaS出海的第一步
• 出海第一站：為什麼選擇東南亞 — 多語言產品在東南亞市場的落地實戰

阿公寄語：寫code嗰陣唔好諗住淨係俾中國香港人用。你永遠唔知你嘅產品將來會去到邊個國家。由day one就做好國際化架構。