See Configuration for the YAML schema and loading order.
Required inputs
| Name | Description |
|---|---|
sourceLocale | Source locale (e.g. en) used to find resource files such as **/*.en.resx. Also forwarded to Translator as from=<locale>. |
subscriptionKey | Azure AI Translator subscription key. Pass via secrets. |
endpoint | Translator endpoint URL, e.g. https://api.cognitive.microsofttranslator.com/. |
Common optional inputs
| Name | Default | Description |
|---|---|---|
region | none | Translator resource region (omit for global resources). |
toLocales | all supported | Locales to translate to. Accepts a JSON array (["fr","de"]) or comma-separated values. |
include | none | Newline-separated glob patterns; only matching files are translated. |
exclude | none | Newline-separated glob patterns; matching files are skipped (applied after include). |
configPath | .github/resource-translator.yml | Path to the YAML config file (relative to the workspace root). |
dryRun | false | When true, run translations and emit summaries but do not write files. |
failOnError | true | When true, unexpected errors fail the action; when false, errors are warnings. |
Translator request inputs
These map directly onto Azure AI Translator v3 query parameters. Every one is optional; the Translator defaults apply when unset.
| Name | Default | Description |
|---|---|---|
categoryId | general | Azure Custom Translator category — the industry/domain/tone knob. Forwarded as ?category=.... |
textType | plain | plain or html. Use html only when your resource values are real HTML fragments. |
profanityAction | NoAction | NoAction, Marked, or Deleted. Controls how profane terms are emitted in translations. |
profanityMarker | Asterisk | Asterisk or Tag. Only meaningful when profanityAction is Marked. |
allowFallback | true (Translator default) | When false, Translator returns an error instead of falling back to the general system if your categoryId has no deployment for a target locale. |
apiVersion | 3.0 | Translator REST API version. |
Resilience & placeholder protection
These inputs control how the action behaves when Translator throttles your request and how it shields placeholder tokens like {{name}} or {0} from being mangled during translation.
| Name | Default | Description |
|---|---|---|
maxRetries | 5 | Maximum retry attempts on transient HTTP responses (408, 425, 429, 500, 502, 503, 504). The total number of HTTP calls per request is 1 + maxRetries. |
retryBackoffMs | 30000 | Cap (in milliseconds) on any single backoff sleep. The action honors Azure's Retry-After response header exactly when present; otherwise it uses jittered exponential backoff capped at this value. |
protectPlaceholders | true | When true (default), placeholders such as {{name}}, ${var}, {0}, {0:N2}, %s, %1$s and HTML entities are replaced with sentinel tokens before translation and restored afterward. Disable only when your source intentionally contains literal placeholder-shaped text that should be translated. |
customPlaceholderPatterns | none | Newline-separated regexes (without delimiters) added to the default placeholder set, e.g. <<.+?>> for custom token syntax. |
noTranslatePatterns | none | Newline-separated 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 Translator request and pass through with their source value preserved. |
Outputs
| Name | Description |
|---|---|
summary-title | Short PR-title-friendly summary, e.g. Machine-translated 320 files, a total of 5,418 translations. |
summary-details | Markdown summary suitable for a PR body or job summary. |
has-new-translations | 'true' when one or more new translations were generated. |