配置 · 资源译器

若需非默认位置,则以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>

译后之词可覆写。词界感知(处理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

凡单次后退睡眠,皆为上限(毫秒)。默认为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/重文本鍵)相匹配。匹配密钥自请求中弃之,传递时其源值得以保留。

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则剔除粗俗词汇,针对年轻群体本地化。

择尔之言

仓库配置

结构

场域参考

装载顺序

語氣與工業,簡言之