Web Frontend i18n
=======

> 目前是個速記格式，未來前面加個動機、後面加個結語，可能會發展成 medium 文章

## 評估前端使用的 i18n solution

i18n 基本上由兩種檔案組成：

1. 💻 要支援多國語言的程式碼。待翻譯的字串可能會有這些問題：
* 有可能位在 view 裡頭（React 的 lifecycle 裡）。
* 有可能位在 view 外面（constants, redux actions, etc），這裡沒有 React context 可以用。
* 需要支援單複數。
* 有可能會需要 interpolation（例如說「您的檔案 ${fileName} 已經刪除」）
* 有可能會夾雜 HTML 標籤（例如說「請按<a>這裡</a>來繼續」）

2. 📖 翻譯檔 message catalogs（每個語言一份），是程式碼內的 key，與實際翻譯文字的 mapping document。

下面會從最單純（也最土砲）的方式開始介紹各種不同工具在上述問題的比較。

## 純土炮 key-value based solution

### 💻 待翻譯程式：引入一個超大 map，印出 map 的某個 value

完全不用任何 library 的 i18n，就是在程式碼裡面每個要翻譯的字串，都用類似 `transObj[langKey][strKey]` 取代，其中
- `transObj` 就是翻譯檔總匯，包含所有語言。需要被 import 到每一個要翻譯的 JS 檔案裡頭。
- `langKey` 就是現在的語言 key（`"zh-TW"` 或 `"ja"` 之類）。
- `strKey` 就是該字串在翻譯檔裡的代號。

利用 JS 的語言特性，其實我們可以把 `transObj` 與 `langKey` 包起來，export 出一個 `(strKey) => 翻譯後字串` 的 function（通常會叫做 `t()` 之類的），以及設定 `langKey` 的 setter function (通常會叫做`setLocale()` 之類的) 就好，這樣每個檔案就只要引入那個 `strKey => 翻譯字串` function 就可以了。

要區分單複數的情況，可能可以用不同的 `strKey` 來分別代表單數與複數的情形。

至於 interpolation、HTML 標籤夾雜的狀況，可能就各自為政、自求多福了。

### 📖 翻譯檔：Map language & keys to strings

重點就是要蓋出上面的那個 `transObj`。它可以是個雙層的 object 放在 JSON 裡，或者是其他的任何格式。

### 誰在用這個方法

- [Rails i18n API](http://guides.rubyonrails.org/i18n.html) 只要把 yml 放在指定的資料夾，就能自動載入 `transObj` 到 Rails view 裡頭。
- g0v summit 2014
- [翻譯檔](https://github.com/g0v/archive-summit-2014/blob/f8859a841a117b408970e80c56acbba4f6a967f2/app/jsons/header.json)
- [被翻譯的程式](https://github.com/g0v/archive-summit-2014/blob/f8859a841a117b408970e80c56acbba4f6a967f2/app/javascripts/components/MainInfo/index.jsx#L23)

## react-intl

### 💻 待翻譯程式
### 📖 翻譯檔

## i18next

### 💻 待翻譯程式

大致上是使用 `i18n.t` 把 key 換成 translated value。

不過 react-i18next 多提供了 `<Trans>` component，原文（英文）可以直接留在程式碼裡面做為預設語言，不用為原文另外準備一套翻譯檔。

`<Trans>` 也可以處理 HTML 標籤夾雜的狀況；在 translated value 裡面使用 `<0>` `</0>` 就能對應到實際程式碼裡頭相對應的 tag，

### 📖 翻譯檔：可以全自動生成的 json

翻譯檔是[JSON 格式](https://www.i18next.com/misc/json-format.html)。

有工具可以自動 extract：http://i18next.github.io/i18next-scanner/

extract 第二次的時候，會跟現有翻譯合併

翻譯檔看不出來是從哪個檔案 extract 出來的，希望大家的翻譯 key 都能 unique 呢。

## [js-lingui](https://github.com/lingui/js-lingui)

### 💻 待翻譯程式：ICU format

基本上可以整個取代 `react-intl`⋯⋯

### 📖 翻譯檔：可以全自動生成的 json

雖然格式有所不同，但有自動化工具、抽出來之後看不出來是從哪個檔案 extract 出來這點基本上差不多。
似乎跟 i18next 差不多。

## [es2015-i18n-tag](http://i18n-tag.kolmer.net/)

### 💻 待翻譯程式：鼓勵直接寫英文！

翻譯的 key `langKey` 就是英文原文字串。

外頭包 `t`

Tagged template 處理 interpolation

#### 特色：[支援 compile-time 翻譯](https://github.com/skolmer/babel-plugin-i18n-tag-translate#example)

- 翻譯檔不會被傳到前端；他會直接被 babel plugin compile 進 source code，in-place 取代掉原本的英文
- 優點：
1. 省頻寬、省載入時間
2. **搞i18n居然不用載入翻譯檔，真的無敵潮！根本聖杯！！**
- 缺點（聖杯的代價）：
1. 你要支援 n 個語言，就得 compile n 個 binary 出來
2. 換語言 = 換整套 application 的 js binary，可能會需要設定 nginx 來處理
3. 理論上無法與 next.js 整合，因為 next.js 把 compilation 與 app instantiation 握在自己手上。
4. 如果你不搞 compile-time 翻譯，那 translation key 是英文原文，就會讓程式碼有點大⋯⋯

### 📖 翻譯檔：手動自己蓋的 JSON，但有工具可以跟程式碼互相驗證。

他不像 js-lingui 那樣自動生成翻譯檔，所以翻譯檔本身可能還是要手動複製貼上 key 到你自己的 JSON。

但是他可以從程式檔生成的 [json schema](https://github.com/skolmer/i18n-tag-schema)，來驗證你的 JSON：
- 程式碼有某字串，但 JSON 裏沒有
- JSON 裏有某 key，程式碼裏沒有
- JSON key 與 value 的 interpolation `${}` 是否都有正確對應

## ttag.js

### 💻 待翻譯程式：直接寫英文！

同 es2015-i18n-tag，使用 `t` tagged tempalte。

`ngettext` tagged template 處理單複數

跟 HTML 混用：目前是用詭異的 [`jt`]() 解，
未來有[新的方式]()。

#### 也有 compile-time 翻譯

同 js-lingui。也可以[載入翻譯檔](https://github.com/c-3po-org/c-3po/issues/103)就是了。

### 📖 翻譯檔：全自動生成 gettext 格式 pot 檔

類似 js-lingui，不過他是用 babel plugin 掃一次你所有的 source code，然後自動產生翻譯檔樣板（`.pot`）

再使用 gettext 的 `msgmerge` 把翻譯檔樣板跟之前的翻譯檔（`.po`）做合併，他會自動地：
- 加入程式碼中的新字串
- 把程式碼裡已經不使用的字串翻譯加上註解
- 如果有相近的字串，會填上現有的相近翻譯，然後標上 fuzzy tag 讓你人工檢查
- 在每個 entry 上面標註這一行是從哪個檔案哪一行 extract 出來的

這個部分由於採用 gettext 這套成熟系統與格式，所以比自幹格式的 js-lingui 強。

### 特色

#### Gettext 生態系

- [translate-toolkit](http://docs.translatehouse.org/projects/translate-toolkit/en/latest/) CLI 系列工具可以合併 po files（`pomerge`）、debug po files (`podebug`)
- 各種 IDE、Translation management system、多人協作翻譯系統的支援

## fbt