為什麼選擇 yaku？

yaku 是一個在終端機中翻譯文字、檔案和結構化文件的 CLI 工具。安裝後執行 yaku --to zh-TW "Hello"，就能得到翻譯結果——不需要 API key、不需要帳號、不需要任何設定。

yaku 的設計是為了處理真實世界的檔案：翻譯 Markdown 時不會破壞格式、翻譯 JSON 和 YAML 時只動值而不動 key，還能透過術語表檔案來統一用語。它從 stdin、檔案或參數讀取輸入，並輸出到 stdout，能自然地融入腳本和 pipe 工作流。

這個頁面幫助你判斷 yaku 是否適合你的需求。

yaku 能做什麼

翻譯不同語言之間的文字 ——支援 LLM 後端所支援的任何語言對。
潤飾文章 ——改善你以非母語撰寫的文字，提升文法和流暢度，而不進行翻譯。
保留結構 ——翻譯 Markdown、JSON 和 YAML 時不破壞格式。Key、程式碼區塊、URL 和 front matter 都保持原樣。
控制術語 ——術語表檔案可以鎖定特定詞彙的翻譯方式，或讓它們保持不翻譯。
融入 pipe 工作流 ——預設從 stdin 讀取、輸出到 stdout，可以和 curl、gh、git、jq 以及任何其他 CLI 工具組合使用。

yaku 不做的事

yaku 的範疇是幫助你跨越語言障礙。超出這個範疇的功能被刻意排除：

不在範疇內	改用
程式碼生成或解釋	通用 AI CLI（`llm`、`aichat`、`sgpt`）
文字摘要	通用 AI CLI
問答或對話	ChatGPT、Claude 或通用 AI CLI
格式轉換（例如 Markdown → HTML）	`pandoc`
不涉及翻譯情境的拼字檢查	`aspell`、`languagetool`
圖形介面翻譯	Google 翻譯、DeepL

**簡單判斷法：**如果一個任務不涉及跨越語言障礙，yaku 就不是正確的工具。

yaku 和其他工具的比較

vs. Google 翻譯 / DeepL / ChatGPT

這些是瀏覽器工具。你必須離開終端機、複製文字、貼上、取得結果，再貼回來。yaku 省去這個來回：

# 不用再複製貼上到瀏覽器：
echo "Bonjour, comment ça va ?" | yaku --to zh-TW
cat error.log | yaku --to zh-TW --context "nginx error log"
yaku --to zh-TW -f README.en.md -o README.md

yaku 還能保留檔案結構（JSON key、Markdown 格式），並支援術語表的術語控制——這些都是瀏覽器工具做不到的。

vs. 通用 AI CLI（`llm`、`sgpt`、`aichat`）

這些工具把任意 prompt 傳給 LLM。你可以用它們翻譯，但每次都要自己寫 prompt：

# 使用通用 AI CLI：
echo "Hello" | llm "translate this to Traditional Chinese"

# 使用 yaku：
echo "Hello" | yaku --to zh-TW

差別在於：

	yaku	通用 AI CLI
Prompt 工程	內建，針對翻譯品質調校	你自己寫 prompt
格式保留	自動處理 Markdown、JSON、YAML	手動（希望 LLM 遵循你的指示）
術語表支援	內建（`.yaku-glossary.yaml`）	沒有
輸出乾淨度	已清理——不會有「以下是翻譯：」之類的前言	原始 LLM 輸出
範疇	僅翻譯和潤飾	任何你能 prompt 的事

如果你需要一把處理所有 AI 任務的萬用工具，用 llm 或 aichat。如果你要可靠、有結構、術語一致的翻譯，用 yaku。

vs. Translate Shell（`trans`）

Translate Shell 使用傳統翻譯引擎（Google、Bing），不是 LLM。它快速且免費，但：

沒有格式感知——無法在保留 key 的同時翻譯 JSON/YAML
沒有術語表或術語控制
翻譯品質受限於底層引擎（常常太直譯、不自然）
沒有潤飾模式

Translate Shell 適合快速查詞。yaku 更適合開發者文件、結構化檔案和對品質有要求的翻譯。

什麼時候該用 yaku

你經常翻譯開發文件（文件、i18n 檔、README、錯誤訊息）。
你想讓整個專案的術語保持一致（術語表）。
你處理結構化檔案（Markdown、JSON、YAML），需要保留結構。
你以非母語寫作，想要潤飾你的文字。
你想把翻譯納入腳本或 CI/CD 流程。

什麼時候不該用 yaku

你需要通用 AI 助手 ——yaku 只做翻譯和潤飾。程式碼生成、摘要或問答請用 llm、aichat 或 sgpt。
你需要即時互動對話 ——yaku 是無狀態的（一個輸入，一個輸出）。來回對話請用 ChatGPT 或 Claude。
你需要完全離線、零設定的翻譯 ——yaku 需要網路連線（託管服務）或本地執行的 LLM（例如 Ollama）。它不內建模型。
你需要圖形介面翻譯 ——yaku 只在終端機使用。瀏覽器翻譯請用 Google 翻譯或 DeepL。