設定

設定檔

yaku 將設定儲存在一個 YAML 檔案中。使用以下指令找到檔案位置：

yaku config path

當你首次執行 yaku config set 時，檔案會自動建立。你也可以直接編輯它——yaku 會保留註解和格式。

所有設定欄位

欄位	類型	預設值	說明
`api-key`	`string`		自備 API 後端（Gemini、OpenAI、Anthropic）的 LLM API key。
`default-target`	`string`		預設目標語言。設定後可省略 `--to`。
`backend`	`string`	`hosted`	LLM 後端：`hosted`、`gemini`、`openai`、`anthropic`。設定時會驗證。
`model`	`string`	`backend` 預設值	覆蓋模型名稱（例如 `gemini-2.5-flash`、`gpt-4o-mini`）。
`api-base`	`string`		任何自備 API 後端的 API base URL 覆寫。常用於 OpenAI 相容供應商。
`hosted-url`	`string`	`https://api.yakulang.com`	託管服務 API 端點。認證端點會自動推導（移除 `api.` 前綴）。
`prompt`	`string`		自訂系統提示詞檔案路徑。套用至每次翻譯。

設定檔範例

api-key: AIzaSy...your-gemini-key
default-target: zh-TW
backend: gemini
model: gemini-2.5-flash

管理設定

# 設定一個值
yaku config set default-target zh-TW

# 讀取一個值（僅從檔案讀取，忽略環境變數）
yaku config get default-target

# 找到設定檔
yaku config path

環境變數

環境變數會覆蓋設定檔的值。這在 CI/CD、容器或切換專案時很有用。

變數	覆蓋的設定欄位	範例
`YAKU_API_KEY`	`api-key`	`export YAKU_API_KEY=AIza...`
`YAKU_DEFAULT_TARGET`	`default-target`	`export YAKU_DEFAULT_TARGET=zh-TW`
`YAKU_BACKEND`	`backend`	`export YAKU_BACKEND=openai`
`YAKU_MODEL`	`model`	`export YAKU_MODEL=gpt-4o`
`YAKU_API_BASE`	`api-base`	`export YAKU_API_BASE=https://api.groq.com/openai/v1`
`YAKU_HOSTED_URL`	`hosted-url`	`export YAKU_HOSTED_URL=https://api.staging.yakulang.com`

環境變數覆蓋行為

當 YAKU_* 環境變數被設定時——即使是空字串——它會覆蓋對應的設定檔值。這能防止 key 來源失敗時產生靜默回退：

# 明確設為空 → 覆蓋設定檔，key 變成空的
YAKU_API_KEY="" yaku --backend gemini --to zh-TW "test"
# Error: YAKU_API_KEY is set but empty (check your key source).

後端專屬的 API key 回退

當 YAKU_API_KEY 完全未設定（甚至沒有設為空字串），且設定檔中也沒有 api-key 時，yaku 會根據解析後的後端（包含 --backend 選項）檢查以下後端專屬的環境變數：

後端	回退變數
`gemini`	`GOOGLE_API_KEY`
`openai`	`OPENAI_API_KEY`
`anthropic`	`ANTHROPIC_API_KEY`

這表示你可以直接使用其他工具（如 Google Cloud SDK 或 OpenAI CLI）已有的環境變數，不需額外設定。搭配 --backend 即可在不同供應商之間自由切換：

export GOOGLE_API_KEY=your-gemini-key
export OPENAI_API_KEY=your-openai-key
yaku --backend gemini --to zh-TW "Hello"
yaku --backend openai --to zh-TW "Hello"

優先順序

同一個設定在多處指定時，優先順序最高的來源勝出：

命令列選項（最高）— 例如 --to ja
環境變數 — 例如 YAKU_DEFAULT_TARGET=ja
設定檔 — ~/.config/yaku/config.yaml
內建預設值（最低）

範例： 如果設定檔中有 default-target: zh-TW，但你執行 yaku --to ja，目標語言就是 ja。

錯誤處理

缺少設定檔： yaku 使用內建預設值，不會報錯。
YAML 語法錯誤： yaku 在 stderr 記錄警告，然後以預設值繼續執行。
未知的設定鍵： yaku config set 會拒絕不在上方列表中的鍵。
無效的設定值： yaku config set 會驗證值。backend 必須是 hosted、gemini、openai、anthropic 其中之一。default-target 必須是有效的 BCP 47 語言代碼。