配置 · 資源翻譯器

如果你需要非預設位置，可以用 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>咁短字串就唔會自動偵測。

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

Translator 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

任何單次退後睡眠都要用上限（ms）。預設係30000。 Azure 嘅Retry-After頭喺出現時會被尊重; 否則會用抖動指數退縮，限制喺呢個值。

protectPlaceholders

類型: boolean

預設係true。開啟時，{{name}}、${var}、{0}、{0:N2}、%s、%1$s 同 HTML 等 token 喺翻譯前會被 sentinel tokens 取代，翻譯後會恢復。只有當源碼有意包含佔位符形狀嘅文字時先停用。

customPlaceholderPatterns

類型: string[]

額外嘅正則表達式模式（冇分隔符）加入預設佔位符集，例如<<.+?>>用於自訂令牌語法。無效嘅正則表達式會被忽略。

noTranslatePatterns

類型: string[]

Glob 模式會同解析器層級嘅鍵（例如 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 Translator v3 API 冇單一音色旋鈕。有兩個設定可以組合起嚟，令你大部分控制都差唔多：

行業 / 領域： 用 categoryId 指向用你自己語料庫訓練嘅 Azure Custom Translator 類別——法律、技術、醫療、市場營銷或者其他範疇。呢個係判斷語氣、品牌聲音同詞彙最強嘅槓桿。
表面文字： 用詞彙表逐字鎖定品牌名同產品術語，喺針對年輕觀眾嘅本地化時用profanityAction刪除粗口。

揀你嘅語言

儲存庫配置

結構

現場參考

載入順序

簡單嚟講，就係語氣同工業