配置 · 資源翻譯器

如果你需要非預設位置，可以用 configPath 輸入覆蓋路徑。

結構

# .github/resource-translator.yml
sourceLocale: en

# Provider config can be nested. Keep secrets in workflow inputs; use repo
# config for non-secret defaults like region, model, formality, or category.
provider:
  azure:
    categoryId: my-custom-translator-category
    apiVersion: "3.0"
    allowFallback: true

toLocales:
  - fr
  - de
  - es
include:
  - "src/**/*.en.json"
  - "apps/**/*.en.resx"
exclude:
  - "**/__tests__/**"
glossary:
  Acme: Contoso
  Octocat: Octocat   # keep brand names verbatim

# Translator request shape — most users can ignore these.
textType: plain                  # plain | html
profanityAction: NoAction        # NoAction | Marked | Deleted
profanityMarker: Asterisk        # Asterisk | Tag (only when profanityAction == Marked)

# Resilience — Translator returns 429 under load. Defaults are usually
# fine; tune only if your runs are large enough to hit them.
maxRetries: 5
retryBackoffMs: 30000             # cap on any single backoff sleep (ms)

# Placeholder protection. ON by default — wraps tokens like {{name}},
# {0}, %s, ${var} into sentinels before translation and restores them
# on the way back. Set false only when source intentionally contains
# placeholder-shaped literals.
protectPlaceholders: true
customPlaceholderPatterns:
  - "<<.+?>>"                     # any extra token syntax you use

# Per-key opt-out. Keys matching any glob are dropped from the request
# and pass through with the source value preserved.
noTranslatePatterns:
  - "errors.code.*"
  - "brands.*"

現場參考

provider

類型: "azure" | "aws" | "google" | provider block

Either a provider string or a nested provider block (provider.azure, provider.aws, or provider.google). Prefer nested blocks for provider-specific settings; keep secrets in workflow inputs rather than committed config.

sourceLocale

類型: string

如果沒設定，會回退到sourceLocale輸入。也會像from=<locale>轉發到 Translator，這樣短字串就不會自動偵測。

toLocales

類型: string[]

可以是陣列或逗號分隔的字串。

include / exclude

類型: string[]

球狀模式會以絕對路徑與工作空間相對路徑進行評估。

glossary

類型: map<string,string>

翻譯後的術語會覆蓋。字邊界感知（handles C++、.NET）。

categoryId

類型: string

Azure Custom Translator 類別 — 你的產業/領域旋鈕（法律、醫療、行銷語氣等）。以?category=...形式發送。

textType

類型: "plain" | "html"

預設是plain。只有當你的資源值包含真實的 HTML 片段時才使用 html。

profanityAction

類型: "NoAction" | "Marked" | "Deleted"

如何在翻譯輸出中處理粗俗詞彙。

profanityMarker

類型: "Asterisk" | "Tag"

只有當profanityAction "Marked"時才有意義。

allowFallback

類型: boolean

設定為 false，當 categoryId 沒有針對目標區域部署時，轉換失敗，而不是回退到一般模型。

apiVersion

類型: string

翻譯器 REST API 版本。預設是3.0。

awsFormality

類型: "FORMAL" | "INFORMAL"

AWS Translate formality setting for supported target languages.

awsBrevity

類型: boolean

Set to true to enable AWS Translate brevity mode for supported language pairs.

awsTerminologyNames / awsParallelDataNames

類型: string[]

AWS Translate custom terminology and parallel data resource names. Either an array or comma-separated string.

googleModel

類型: string

Google Cloud Translation model, e.g. nmt or base.

googleApiEndpoint

類型: string

Optional Google Cloud Translation API endpoint override.

googleAutoRetry

類型: boolean

Optional Google Cloud Translation automatic retry toggle. Leave unset to use the Google client default.

maxRetries

類型: integer

暫時 HTTP 回應的最大重試次數（408, 425, 429, 500, 502, 503, 504）。預設是5。每個請求的 HTTP 呼叫總數為 1 + maxRetries。

retryBackoffMs

類型: integer

任何單次退避睡眠都要用 cap（ms）。預設是30000。Azure的Retry-After頭在出現時會被精確尊重;否則則使用抖動指數退縮，並限制在此值。

protectPlaceholders

類型: boolean

預設是true。啟用時，像 {{name}}、${var}、{0}、{0:N2}、%s、%1$s 和 HTML 等標記在轉換前會被哨兵標記取代，轉換後則恢復。只有當原始碼故意包含佔位符形狀的字面時才會停用。

customPlaceholderPatterns

類型: string[]

在預設佔位符集中加入了額外的正則表達式模式（不含分隔符），例如用於自訂標記語法的 <<.+?>>。無效的正則表達式會被忽略。

noTranslatePatterns

類型: string[]

球狀模式與解析器層級鍵（JSON點路徑、RESX name、PO msgid、XLIFF 單位 id、INI/restext 鍵）相匹配。匹配的金鑰會從請求中被刪除，並保留其來源值通過。

changeDetection

類型: "smart" | "disabled"

Defaults to smart. Uses the committed state manifest to translate only changed or missing parser keys. Set to disabled or false to preserve the legacy always-translate behavior.

statePath

類型: string

Path to the deterministic smart change-detection state manifest. Defaults to .github/resource-translator-state.json.

載入順序

這個動作會讀取工作流程中的明確輸入。
它會從 configPath 載入 YAML 設定。
每共用一個欄位，輸入會勝出;否則則使用 YAML 值。
合併後的值會被驗證。無效的枚舉（例如 profanityAction: Mask）會使動作快速失敗且訊息為清晰。

簡單來說，就是語氣和工業

Azure AI 翻譯器 v3 API 沒有單一音調旋鈕。兩種設定結合起來，讓你擁有大部分相同的控制：

產業/領域： 用 categoryId 指向一個用你自己語料庫訓練的 Azure Custom Translator 類別——法律、技術、醫療、行銷或其他任何領域。這是判斷語氣、品牌聲音和詞彙最強的槓桿。
表面文字： 利用詞彙表逐字鎖定品牌名稱和產品術語，並在針對年輕族群的本地化時，用 profanityAction 刪除髒話。

選擇你的語言

儲存庫配置

結構

現場參考

載入順序

簡單來說，就是語氣和工業