# 翻譯 Netstamp

透過 Crowdin 貢獻翻譯、妥善保留技術內容，並在發布前驗證本地化資源。

Netstamp 以英文作為來源語言，目前支援台灣繁體中文 `zh-TW`。如果只是協助翻譯，不需要先在本機設定程式碼儲存庫，也不需要 Crowdin API 權杖。

## 不需寫程式也能參與翻譯

1. 開啟 [Netstamp Crowdin 專案](https://crowdin.com/project/netstamp)，登入或建立免費帳號。
2. 選擇 **Chinese Traditional (`zh-TW`)**，再開啟要翻譯的檔案。你也可以用 Crowdin 的篩選器只顯示未翻譯或尚未核准的字串。
3. 選取字串後，先閱讀英文原文、前後文、來源檔案路徑及其他譯者留下的留言。翻譯記憶庫提供的內容只能當作參考，請不要未經確認就直接採用。
4. 在譯文欄輸入自然、完整的台灣繁體中文。可先搜尋專案中相同詞彙的既有譯法，讓用語保持一致。
5. 儲存前先處理 Crowdin 顯示的品質檢查警告，特別留意變數、標籤、數字、標點與空白是否和原文相符。
6. 如果英文原文有歧義，或正確譯法取決於產品實際行為，請在該字串下留言並標記維護者，不要自行猜測。

送出翻譯後，維護者會在 Crowdin 審閱與核准，再將譯文同步回程式碼儲存庫。翻譯貢獻者不需要 `CROWDIN_PROJECT_ID`、`CROWDIN_PERSONAL_TOKEN`，也不需要程式碼儲存庫的寫入權限。

## 哪些內容需要翻譯

請翻譯所有使用者會看到的文字，包括：

- 導覽、標題、說明、按鈕、表單標籤、輸入提示、工具提示、空白狀態、錯誤訊息與無障礙標籤；
- 說明文件標題、frontmatter 中的 `description`、段落、清單、提示框文字與連結文字；
- 在地化後的頁面標題、中繼資料與圖片替代文字。

請使用台灣慣用語，例如「設定」、「檔案」、「連線」、「使用者」、「資訊」、「程式碼」與「伺服器」，不要套用中國大陸用語或逐詞硬翻。

Netstamp 的產品用語也應前後一致。例如 Probe 在一般說明中譯為「探測器」、Controller 譯為「控制器」、check 譯為「檢查」、assignment 譯為「指派」，token 則依情境譯為「權杖」。程式碼中的型別、欄位或元件名稱仍須保留原文。

## 哪些內容必須原樣保留

除非英文來源明確提供在地化名稱，以下內容都應保持原樣：

- `Netstamp`、API 名稱、通訊協定名稱，以及 `HTTP`、`TLS`、`DNS`、`ICMP`、`OpenAPI` 等技術識別名稱；
- 程式碼區塊、行內程式碼、命令、檔案路徑、URL、電子郵件地址、JSON key 與環境變數名稱；
- `{{name}}` 這類插值變數、複數後綴、預留位置、MDX import、元件標籤與 frontmatter 結構；
- 標題錨點與連結目的地。

:::warning 絕對不要翻譯、改名或刪除插值變數。英文若包含 `Welcome, {{name}}`，譯文中也必須保留完全相同的 `{{name}}`。 :::

## Crowdin 翻譯者的工作流程

Crowdin 會從下列路徑上傳英文來源：

```text
web/src/i18n/locales/en/*.json
docs/src/i18n/locales/en/ui.json
docs/src/content/docs/en/**/*.mdx
```

翻譯完成後，Crowdin 會將輸出寫到對應的 `zh-TW` 路徑。除非同一項修正已經先在 Crowdin 完成，否則不要只修改 Crowdin 管理的 `zh-TW` 檔案並送出 pull request；下一次下載譯文時，這類本機修改可能會被覆寫。

新的英文文字在等待翻譯期間，可能會因英文備援機制而暫時出現在其他語言的畫面。這是預期行為，不需要因此擋下內容正確的英文來源 pull request。

## 開發者與維護者：新增來源文字

開發者新增使用者看得到的文字時，應依序完成：

1. 在合適的英文命名空間新增語意清楚的 key，不要直接把整句英文當作 key。
2. 使用既有的 i18n 輔助函式或 `useTranslation("namespace")`；React 的結構化內容請使用 `<Trans>`。
3. 英文說明文件一律放在 `docs/src/content/docs/en/` 下，並保留程式碼、import、元件標籤、標題錨點與檔案路徑。
4. 執行本地化驗證與受影響的測試。
5. 只把英文來源上傳至 Crowdin；不可把 `zh-TW` 當成來源語言上傳。

```bash
pnpm check:i18n
pnpm test:i18n
pnpm test:web
pnpm test:docs:i18n
```

具備 Crowdin 憑證的維護者可使用下列指令同步檔案：

```bash
pnpm crowdin:upload
pnpm crowdin:download
pnpm check:i18n
```

憑證應設定在 shell、本機且已被忽略的 `.env`，或 CI 的機密儲存空間。絕對不要提交 Crowdin API 權杖或任何已填入憑證的檔案。

## 審閱與疑難排解

翻譯發布前，請確認 Crowdin 的品質檢查沒有尚未處理的變數或標籤不一致問題、在地化路由可以順利建置、內部連結會留在使用者選擇的語言，而且程式碼範例完全沒有改變。因台灣用語造成的標點或大小寫警告，可以在人工確認後略過；缺少預留位置、標籤、數字或程式碼則一定要修正。

語系架構、新增語言、檔案管理權責與 CLI 疑難排解，請參閱程式碼儲存庫中的[本地化維護指南](https://github.com/yorukot/netstamp/blob/main/docs/localization.md)。