Configuration · Resource Translator

Override the path with the configPath input if you need a non-default location.

Schema

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

# Domain / industry — uses an Azure Custom Translator category trained on
# your tone and vocabulary. Leave unset for the general model.
categoryId: my-custom-translator-category

# 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)
allowFallback: true              # false fails when the categoryId has no deployment

apiVersion: "3.0"

# 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.*"

Field reference

Configuration field reference
Field	Type	Notes
`sourceLocale`	string	Falls back to the `sourceLocale` input if not set. Also forwarded to Translator as `from=<locale>` so short strings aren't autodetected.
`toLocales`	string[]	Either an array or a comma-separated string.
`include` / `exclude`	string[]	Glob patterns evaluated against absolute and workspace-relative paths.
`glossary`	map<string,string>	Post-translation term overrides. Word-boundary aware (handles `C++`, `.NET`).
`categoryId`	string	Azure Custom Translator category — your industry/domain knob (legal, medical, marketing tone, etc.). Sent as `?category=...`.
`textType`	`"plain"` \| `"html"`	Defaults to `plain`. Use `html` only if your resource values contain real HTML fragments.
`profanityAction`	`"NoAction"` \| `"Marked"` \| `"Deleted"`	How to treat profane terms in translated output.
`profanityMarker`	`"Asterisk"` \| `"Tag"`	Only meaningful when `profanityAction` is `"Marked"`.
`allowFallback`	boolean	Set to `false` to fail the translation when your `categoryId` has no deployment for a target locale instead of falling back to the general model.
`apiVersion`	string	Translator REST API version. Defaults to `3.0`.
`maxRetries`	integer	Maximum retry attempts on transient HTTP responses (`408, 425, 429, 500, 502, 503, 504`). Defaults to `5`. Total HTTP calls per request is `1 + maxRetries`.
`retryBackoffMs`	integer	Cap (ms) on any single backoff sleep. Defaults to `30000`. Azure's `Retry-After` header is honored exactly when present; otherwise jittered exponential backoff is used, capped at this value.
`protectPlaceholders`	boolean	Defaults to `true`. When on, tokens like `{{name}}`, `${var}`, `{0}`, `{0:N2}`, `%s`, `%1$s` and HTML entities are replaced with sentinel tokens before translation and restored afterward. Disable only when source intentionally contains placeholder-shaped literals.
`customPlaceholderPatterns`	string[]	Extra regex patterns (without delimiters) added to the default placeholder set, e.g. `<<.+?>>` for custom token syntax. Invalid regexes are ignored.
`noTranslatePatterns`	string[]	Glob patterns matched against parser-level keys (JSON dotted path, RESX `name`, PO `msgid`, XLIFF unit `id`, INI/restext key). Matching keys are dropped from the request and pass through with their source value preserved.

Loading order

The action reads explicit inputs from the workflow.
It loads the YAML config from configPath.
For every shared field, the input wins; otherwise the YAML value is used.
The merged values are validated. Invalid enums (e.g. profanityAction: Mask) cause the action to fail fast with a clear message.

Tone and industry, in plain terms

The Azure AI Translator v3 API does not have a single tone knob. Two settings combine to give you most of the same control:

Industry / domain: use categoryId to point at an Azure Custom Translator category trained on your own corpus — legal, technical, medical, marketing, or anything else. This is the strongest lever for tone, brand voice, and vocabulary.
Surface text: use the glossary to lock brand names and product terms verbatim, and use profanityAction to scrub profane terms when targeting localization for younger audiences.

Choose your language

Repository configuration

Schema

Field reference

Loading order

Tone and industry, in plain terms