Inputs & outputs · Resource Translator

See Configuration for the YAML schema and loading order.

Required inputs

sourceLocale

Source locale (e.g. en) used to find resource files such as **/*.en.resx. Also forwarded to the provider as from=<locale>.

Provider selection & credentials

Choose one provider per run with provider. It can be a simple provider name or a nested YAML/JSON block with that provider's credentials and native settings. Flat inputs remain supported and override nested values. See the Inputs & outputs guide for full setup.

provider

Default: azure

Translation provider: azure (default), aws, or google. Only one provider is used per action call.

subscriptionKey

Default: none

Azure AI Translator subscription key. Required for azure. Pass via secrets.

endpoint

Default: none

Azure Translator endpoint URL, e.g. https://api.cognitive.microsofttranslator.com/. Required for azure.

awsAccessKeyId

Default: none

AWS access key id. Optional — omit (with awsSecretAccessKey) to use the AWS default credential chain / OIDC. Pass via secrets.

awsSecretAccessKey

Default: none

AWS secret access key. Must be supplied together with awsAccessKeyId. Pass via secrets.

awsSessionToken

Default: none

Optional AWS session token for temporary credentials. Pass via secrets.

awsRegion

Default: none

AWS region for the Translate service (e.g. us-east-1). Required for aws unless AWS_REGION is set in the environment.

awsFormality

Default: none

AWS Translate formality setting: FORMAL or INFORMAL.

awsBrevity

Default: none

When true, enables AWS Translate brevity mode for supported language pairs.

awsTerminologyNames

Default: none

AWS Translate custom terminology resource names. Accepts a JSON array or comma-separated values.

awsParallelDataNames

Default: none

AWS Translate parallel data resource names. Accepts a JSON array or comma-separated values.

googleApiKey

Default: none

Google Cloud API key. Provide this OR googleCredentials for google. Pass via secrets.

googleCredentials

Default: none

Google Cloud service-account key as a JSON string. Provide this OR googleApiKey for google. Pass via secrets.

googleProjectId

Default: none

Optional Google Cloud project id. Usually inferred from the service-account credential.

googleModel

Default: none

Google Cloud Translation model, e.g. nmt or base.

googleApiEndpoint

Default: none

Optional Google Cloud Translation API endpoint override.

googleAutoRetry

Default: none

Optional Google Cloud Translation automatic retry toggle. Leave unset to use the Google client default.

Common optional inputs

region

Default: none

Translator resource region (omit for global resources).

toLocales

Default: all supported

Locales to translate to. Accepts a JSON array (["fr","de"]) or comma-separated values.

include

Default: none

Newline-separated glob patterns; only matching files are translated.

exclude

Default: none

Newline-separated glob patterns; matching files are skipped (applied after include).

configPath

Default: .github/resource-translator.yml

Path to the YAML config file (relative to the workspace root).

changeDetection

Default: smart

Smart change detection mode. smart translates only keys whose source value, target presence, state entry, or translation-affecting settings require it. Use disabled or false to send every eligible key on every run.

statePath

Default: .github/resource-translator-state.json

Path to the compact deterministic smart change-detection state manifest. Defaults to .github/resource-translator-state.json; commit it so future runs can audit and reuse unchanged translations.

snapshotOnly

Default: false

When true, create/update the smart change-detection manifest from existing source and target files without calling a translation provider or writing target resource files. Useful when bootstrapping statePath while a provider is unavailable.

dryRun

Default: false

When true, run translations and emit summaries but do not write files.

failOnError

Default: true

When true, unexpected errors fail the action; when false, errors are warnings.

Azure Translator request inputs

These map directly onto Azure AI Translator v3 query parameters and apply to the azure provider. textType and profanityAction are also mapped to AWS/Google where an equivalent exists (see the providers guide); the rest are Azure-only. Every one is optional; the Translator defaults apply when unset.

categoryId

Default: general

Azure Custom Translator category — the industry/domain/tone knob. Forwarded as ?category=....

textType

Default: plain

plain or html. Use html only when your resource values are real HTML fragments.

profanityAction

Default: NoAction

NoAction, Marked, or Deleted. Controls how profane terms are emitted in translations.

profanityMarker

Default: Asterisk

Asterisk or Tag. Only meaningful when profanityAction is Marked.

allowFallback

Default: 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

Default: 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.

maxRetries

Default: 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

Default: 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

Default: 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

Default: none

Newline-separated regexes (without delimiters) added to the default placeholder set, e.g. <<.+?>> for custom token syntax.

noTranslatePatterns

Default: 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

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.