配置 · 资源转换器

如果你需要非默认位置，可以用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

任何单次退去睡眠时，上限（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 去除脏话。

选择你的语言

仓库配置

结构

现场参考

装载顺序

简单来说，就是语气和工业