ꯀꯟꯐꯤꯒꯨꯔꯦꯁꯟ · ꯔꯤꯁꯣꯔꯁ ꯇ꯭ꯔꯥꯟꯁ꯭ꯂꯦꯇꯔ

ꯀꯔꯤꯒꯨꯝꯕ ꯅꯍꯥꯛꯅ ꯗꯤꯐꯣꯜꯠ ꯅꯠꯇꯕ ꯃꯐꯝ ꯑꯃ ꯃꯊꯧ ꯇꯥꯔꯕꯗꯤ 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

ꯑꯦꯓꯨꯔ Custom Translator ꯀꯦꯇꯦꯒꯣꯔꯤ — ꯅꯍꯥꯛꯀꯤ ꯏꯟꯗꯁꯇ꯭ꯔꯤ/ꯗꯣꯃꯦꯟ ꯅꯣꯕ (ꯑꯥꯏꯟ, ꯃꯦꯗꯤꯀꯦꯜ, ꯃꯥꯔꯀꯦꯇꯤꯡ ꯇꯣꯟ, ꯑꯁꯤꯅꯆꯤꯡꯕ)꯫ ꯊꯥꯔꯛꯈꯤ ?category=... ꯫

textType

ꯃꯈꯜꯁꯤꯡ: "plain" | "html"

ꯗꯤꯐꯣꯜꯠ ꯇꯨ plain. html ꯅꯍꯥꯛꯀꯤ ꯔꯤꯁꯣꯔꯁ ꯚꯦꯂꯨꯁꯤꯡꯗ ꯑꯁꯦꯡꯕ HTML ꯐ꯭ꯔꯦꯒꯃꯦꯟꯠꯁꯤꯡ ꯌꯥꯎꯔꯕꯗꯤ ꯈꯛꯇꯗ ꯁꯤꯖꯤꯟꯅꯧ꯫

profanityAction

ꯃꯈꯜꯁꯤꯡ: "NoAction" | "Marked" | "Deleted"

ꯍꯟꯗꯣꯛꯂꯛꯄ ꯑꯥꯎꯠꯄꯨꯠꯇ ꯐꯠꯇꯕ ꯋꯥꯍꯩꯁꯤꯡ ꯀꯔꯝꯅ ꯁꯤꯖꯤꯟꯅꯒꯗꯒꯦ ꯫

profanityMarker

ꯃꯈꯜꯁꯤꯡ: "Asterisk" | "Tag"

profanityAction ꯑꯗꯨ ꯍꯦꯛ ꯋꯥꯍꯟꯊꯣꯛ "Marked" ꯫

allowFallback

ꯃꯈꯜꯁꯤꯡ: boolean

ꯅꯍꯥꯛꯀꯤ false categoryId ꯑꯗꯨ ꯖꯦꯅꯔꯦꯜ ꯃꯣꯗꯦꯜꯗ ꯍꯜꯂꯛꯄꯒꯤ ꯃꯍꯨꯠꯇ ꯇꯥꯔꯒꯦꯠ ꯂꯣꯀꯦꯜ ꯑꯃꯒꯤꯗꯃꯛ ꯁꯤꯖꯤꯟꯅꯕ ꯂꯩꯇꯕ ꯃꯇꯝꯗ ꯇ꯭ꯔꯥꯟꯁ꯭ꯂꯦꯁꯟ ꯑꯗꯨ ꯃꯥꯏ ꯄꯥꯛꯇꯅꯕ ꯁꯦꯠ ꯇꯧ꯫

apiVersion

ꯃꯈꯜꯁꯤꯡ: string

ꯍꯟꯗꯣꯛꯂꯣꯏ ꯔꯦꯁ꯭ꯠ ꯑꯦꯄꯤꯑꯥꯏ ꯚꯔꯖꯟ. ꯗꯤꯐꯣꯜꯠ ꯇꯨ 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. ꯑꯦꯓꯨꯔꯒꯤ Retry-After ꯍꯦꯗꯔ ꯑꯁꯤ ꯆꯞꯆꯥꯅ ꯌꯥꯎꯔꯛꯄ ꯃꯇꯝꯗ ꯏꯀꯥꯏ ꯈꯨꯝꯅꯩ; ꯅꯠꯇ꯭ꯔꯕꯗꯤ ꯖꯤꯇꯔꯗ ꯑꯦꯛꯁꯄꯣꯅꯦꯟꯁ꯭ꯌꯦꯜ ꯕꯦꯛꯑꯣꯐ ꯑꯁꯤ ꯁꯤꯖꯤꯟꯅꯩ, ꯃꯁꯤꯒꯤ ꯚꯦꯂꯨ ꯑꯁꯤꯗ ꯀꯦꯞ ꯇꯧꯋꯤ꯫

protectPlaceholders

ꯃꯈꯜꯁꯤꯡ: boolean

ꯗꯤꯐꯣꯜꯠ ꯇꯨ true. ꯑꯣꯟ ꯃꯇꯝꯗ, {{name}}, ${var}, {0}, {0:N2}, %s, %1$s ꯑꯃꯁꯨꯡ ꯑꯩꯆ.ꯇꯤ.ꯑꯦꯝ.ꯑꯦꯜ. ꯑꯦꯟꯇꯤꯇꯤꯁꯤꯡꯒꯨꯝꯕ ꯇꯣꯀꯟꯁꯤꯡ ꯑꯁꯤ ꯍꯟꯗꯣꯛꯇ꯭ꯔꯤꯉꯩ ꯃꯃꯥꯡꯗ ꯁꯦꯟꯇꯤꯅꯦꯜ ꯇꯣꯀꯟꯁꯤꯡꯅ ꯃꯍꯨꯠ ꯁꯤꯟꯏ ꯑꯃꯁꯨꯡ ꯃꯗꯨꯒꯤ ꯃꯇꯨꯡꯗ ꯑꯃꯨꯛ ꯍꯟꯅ ꯍꯟꯖꯤꯟꯍꯜꯂꯤ꯫ ꯁꯣꯔꯁꯅ ꯈꯪꯍꯧꯗꯅ ꯄ꯭ꯂꯦꯁꯍꯣꯜꯗꯔꯒꯤ ꯃꯑꯣꯡꯒꯤ ꯂꯤꯇꯔꯜꯁꯤꯡ ꯌꯥꯎꯔꯛꯄ ꯃꯇꯝꯗꯈꯛꯇ ꯗꯤꯁꯑꯦꯕꯜ ꯇꯧꯕꯤꯌꯨ꯫

customPlaceholderPatterns

ꯃꯈꯜꯁꯤꯡ: string[]

ꯗꯤꯐꯣꯜꯠ ꯄ꯭ꯂꯦꯁꯍꯣꯜꯗꯔ ꯁꯦꯠꯇ ꯑꯍꯦꯟꯕ ꯔꯦꯖꯦꯛꯁ ꯄꯦꯇꯔ꯭ꯟꯁꯤꯡ (ꯗꯤꯂꯤꯃꯤꯇꯔ ꯌꯥꯎꯗꯅ) ꯍꯥꯞꯆꯤꯟꯈꯤ, ꯈꯨꯗꯝ ꯑꯣꯏꯅ ꯀꯁꯇꯝ ꯇꯣꯀꯟ ꯁꯤꯟꯇꯦꯛꯁꯀꯤ <<.+?>>. ꯆꯠꯅꯗꯕ ꯔꯦꯖꯦꯛꯁꯁꯤꯡ ꯑꯁꯤ ꯊꯋꯥꯏ ꯌꯥꯎꯗꯦ꯫

noTranslatePatterns

ꯃꯈꯜꯁꯤꯡ: string[]

ꯒ꯭ꯂꯣꯕ ꯄꯦꯇꯔꯟꯁꯤꯡ ꯑꯁꯤ ꯄꯥꯔꯁꯔ-ꯂꯦꯕꯦꯜ ꯀꯤꯁꯤꯡ (JSON dotted path, RESX name, PO msgid, XLIFF unit id, INI/restext key)ꯒ ꯃꯥꯟꯅꯈꯤ꯫ ꯆꯥꯟꯅꯕ ꯀꯤꯁꯤꯡ ꯑꯗꯨ ꯍꯥꯏꯖꯔꯛꯄ ꯑꯗꯨꯗꯒꯤ ꯂꯧꯊꯣꯛꯏ ꯑꯃꯁꯨꯡ ꯃꯈꯣꯏꯒꯤ ꯁꯣꯔꯁ ꯚꯦꯂꯨ ꯉꯥꯛꯇꯨꯅ ꯊꯝꯗꯨꯅ ꯆꯠꯂꯤ꯫

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 ꯫
ꯌꯦꯟꯅꯔꯤꯕ ꯂꯝꯄꯥꯛ ꯈꯨꯗꯤꯡꯃꯛꯀꯤ ꯑꯣꯏꯅ, ꯏꯟꯄꯨꯠ ꯑꯗꯨ ꯃꯥꯏ ꯄꯥꯛꯏ; ꯅꯠꯇ꯭ꯔꯕꯗꯤ ꯋꯥꯏꯑꯦꯝꯑꯦꯜ ꯚꯦꯂꯨ ꯁꯤꯖꯤꯟꯅꯩ ꯫
ꯄꯨꯟꯁꯤꯟꯅꯔꯕ ꯚꯦꯂꯨꯁꯤꯡ ꯑꯁꯤ ꯚꯦꯂꯤꯗꯦꯠ ꯇꯧꯋꯤ꯫ ꯆꯠꯅꯗꯕ ꯏꯅꯝꯁꯤꯡ (ꯈꯨꯗꯝ ꯑꯣꯏꯅ profanityAction: Mask) ꯑꯁꯤꯅ ꯃꯌꯦꯛ ꯁꯦꯡꯕ ꯄꯥꯎꯖꯦꯜ ꯑꯃꯒ ꯂꯣꯏꯅꯅ ꯊꯧꯋꯣꯡ ꯑꯗꯨ ꯊꯨꯅ ꯃꯥꯏ ꯄꯥꯛꯇꯕ ꯊꯣꯛꯍꯜꯂꯤ꯫

ꯈꯣꯟꯖꯦꯜ ꯑꯃꯁꯨꯡ ꯏꯟꯗꯁꯇ꯭ꯔꯤ, ꯑꯁꯦꯡꯕ ꯋꯥꯍꯩꯗ

ꯑꯦꯓꯨꯔ ꯑꯦꯑꯥꯏ ꯇ꯭ꯔꯥꯟꯁ꯭ꯂꯦꯇꯔ v3 API ꯗ ꯇꯣꯟ ꯅꯣꯕ ꯑꯃꯈꯛ ꯂꯩꯇꯦ꯫ ꯁꯦꯇꯤꯡ ꯑꯅꯤ ꯄꯨꯟꯁꯤꯟꯗꯨꯅ ꯅꯍꯥꯛꯄꯨ ꯆꯞ ꯃꯥꯟꯅꯕ ꯀꯟꯇ꯭ꯔꯣꯜ ꯑꯌꯥꯝꯕ ꯄꯤ:

ꯏꯟꯗꯁꯇ꯭ꯔꯤ / ꯗꯣꯃꯦꯟ: ꯅꯍꯥꯛꯀꯤ ꯃꯁꯥꯒꯤ ꯀꯣꯔꯄꯁꯇ ꯇ꯭ꯔꯦꯟ ꯇꯧꯔꯕ ꯑꯦꯓꯨꯔ Custom Translator ꯀꯦꯇꯦꯒꯣꯔꯤ ꯑꯃꯗ ꯇꯥꯛꯅꯕ categoryId ꯁꯤꯖꯤꯟꯅꯧ — ꯑꯥꯏꯟꯒꯤ ꯑꯣꯏꯕ, ꯇꯦꯛꯅꯤꯀꯦꯜ, ꯃꯦꯗꯤꯀꯦꯜ, ꯃꯥꯔꯀꯦꯇꯤꯡ, ꯅꯠꯇ꯭ꯔꯒ ꯑꯇꯩ ꯑꯃꯍꯦꯛꯇ꯫ ꯃꯁꯤ ꯈꯣꯟꯖꯦꯜ, ꯕ꯭ꯔꯥꯟꯗ ꯈꯣꯟꯖꯦꯜ ꯑꯃꯁꯨꯡ ꯋꯥꯍꯩ ꯄꯔꯦꯡꯒꯤ ꯈ꯭ꯋꯥꯏꯗꯒꯤ ꯃꯄꯥꯡꯒꯜ ꯀꯟꯕ ꯂꯤꯚꯔꯅꯤ꯫
ꯂꯩꯃꯥꯏꯒꯤ ꯋꯥꯍꯩ: ꯕ꯭ꯔꯥꯟꯗ ꯃꯃꯤꯡꯁꯤꯡ ꯑꯃꯁꯨꯡ ꯄꯣꯠꯊꯣꯛꯀꯤ ꯋꯥꯍꯩꯁꯤꯡ ꯑꯗꯨ ꯋꯥꯍꯩꯅ ꯂꯣꯛ ꯇꯧꯅꯕ ꯒ꯭ꯂꯣꯁꯔꯤ ꯁꯤꯖꯤꯟꯅꯧ, ꯑꯃꯁꯨꯡ ꯅꯍꯥ ꯑꯣꯏꯔꯤꯕ ꯑꯌꯦꯡꯕ ꯃꯤꯁꯤꯡꯒꯤꯗꯃꯛꯇ ꯃꯐꯝꯗꯨꯗ ꯊꯝꯕ ꯃꯇꯝꯗ ꯐꯠꯇꯕ ꯋꯥꯍꯩꯁꯤꯡ ꯁꯦꯡꯗꯣꯛꯅꯕ profanityAction ꯁꯤꯖꯤꯟꯅꯧ꯫

ꯅꯍꯥꯛꯀꯤ ꯂꯣꯟ ꯈꯜꯂꯨ

ꯔꯤꯄꯣꯁꯤꯇꯣꯔꯤ ꯀꯟꯐꯤꯒꯨꯔꯦꯁꯟ

ꯁ꯭ꯀꯤꯃꯥ

ꯐꯤꯜꯗ ꯔꯤꯐꯔꯦꯟꯁ

ꯂꯣꯗ ꯇꯧꯕꯒꯤ ꯑꯣꯔꯗꯔ

ꯈꯣꯟꯖꯦꯜ ꯑꯃꯁꯨꯡ ꯏꯟꯗꯁꯇ꯭ꯔꯤ, ꯑꯁꯦꯡꯕ ꯋꯥꯍꯩꯗ