格式感知翻譯

yaku 會偵測輸入格式並調整翻譯策略以保留結構。key、程式碼區塊、URL 及其他不可翻譯的元素維持不變。

格式偵測

yaku 按以下順序判斷格式：

--format 選項 — 明確覆蓋：--format json
-f 的副檔名 — .md、.json、.yaml、.yml
預設值 — 純文字

副檔名	偵測到的格式
`.md`、`.markdown`、`.mdx`	Markdown
`.json`	JSON
`.yaml`、`.yml`	YAML
其他	文字

Markdown

yaku 將整份 Markdown 文件傳送給 LLM，並附加額外規則以保留結構：

yaku --to zh-TW -f README.en.md -o README.zh-TW.md

會翻譯的內容：

段落文字
標題文字
列表項目文字
連結顯示文字（例如 [這部分](url)）
引用區塊文字

維持不變的內容：

標題標記（#、##、###）
程式碼區塊（圍欄式和縮排式）
行內程式碼（反引號）
連結 URL 和圖片路徑
Front matter（--- ... ---）
HTML 標籤
列表和引用標記
檔案路徑、URL 和電子郵件地址

範例

輸入（README.en.md）：

# Quick Start

Install the package:

```bash
npm install my-package
```

See the [documentation](https://example.com) for more details.

yaku --to zh-TW -f README.en.md

輸出：

# 快速開始

安裝套件：

```bash
npm install my-package
```

詳見[文件](https://example.com)。

注意：標題標記、程式碼區塊和 URL 都被保留了，只有散文被翻譯。

JSON

yaku 擷取所有字串值，批次翻譯，再以原始結構重新組裝 JSON：

yaku --to zh-TW -f en.json -o zh-TW.json

會翻譯的內容：

字串值

維持不變的內容：

所有 key
數字、布林值、null
巢狀結構
陣列順序

範例

輸入（en.json）：

{
  "nav": {
    "home": "Home",
    "about": "About Us",
    "contact": "Contact"
  },
  "hero": {
    "title": "Build something great",
    "subtitle": "The fastest way to ship your product",
    "cta": "Get Started"
  },
  "footer": {
    "copyright": "All rights reserved",
    "version": 2
  }
}

yaku --to zh-TW -f en.json -o zh-TW.json

輸出（zh-TW.json）：

{
  "nav": {
    "home": "首頁",
    "about": "關於我們",
    "contact": "聯絡我們"
  },
  "hero": {
    "title": "打造非凡之作",
    "subtitle": "最快將產品推向市場的方式",
    "cta": "立即開始"
  },
  "footer": {
    "copyright": "版權所有",
    "version": 2
  }
}

key、結構和數值 version 欄位完全保留。

YAML

運作方式與 JSON 相同 — 擷取字串值、翻譯、再重新組裝：

yaku --to zh-TW -f en.yaml -o zh-TW.yaml

範例

輸入（en.yaml）：

app:
  name: My Application
  description: A task management tool

messages:
  welcome: Welcome back!
  error: Something went wrong
  confirm: Are you sure?

settings:
  max_retries: 3
  debug: false

yaku --to zh-TW -f en.yaml -o zh-TW.yaml

輸出（zh-TW.yaml）：

app:
  name: 我的應用程式
  description: 任務管理工具

messages:
  welcome: 歡迎回來！
  error: 發生錯誤
  confirm: 確定嗎？

settings:
  max_retries: 3
  debug: false

key、整數和布林值被保留。只有字串值被翻譯 — 包括像 "dark" 或 "urgent" 這樣的短單字值。程式碼識別碼（camelCase、snake_case、ALL_CAPS）和語系代碼（例如 "en"、"zh-TW"）維持原樣。

純文字

預設格式。整段輸入原封不動地傳送給 LLM：

echo "Hello, world" | yaku --to zh-TW
yaku --to zh-TW "Good morning"

不執行結構分析。適用於短文字、段落或任何非結構化內容。

強制指定格式

用 --format 覆蓋自動偵測：

# 將 stdin 視為 Markdown，即使沒有副檔名
cat doc.txt | yaku --to zh-TW --format md

# 將 .txt 檔視為 YAML
yaku --to zh-TW -f data.txt --format yaml