ievangelist/Machine Translator
Automatically open machine-translated pull requests for resource files using Azure, AWS, or Google translation providers. Supports .resx, .restext, .ini, .xliff, .po, and .json.
View on GitHubTrust Signals
- Scorecard Score
- not yet scored
- Maintenance Recency
- Activelast commit Jul 10, 2026
- License
- MIT
Pinned Snippet
uses: ievangelist/resource-translator@3644162f34da29f7c2b742ccaa884f911c451502 # v3.0.2tags can be moved; commit SHAs can't. why a SHA?
Inputs
| name | description | required | default |
|---|---|---|---|
| sourceLocale | Source locale (e.g. 'en') used to find translation files (e.g. **/*.en.resx). | yes | — |
| provider | Translation provider to use: 'azure' (default), 'aws', or 'google'. Also accepts a YAML/JSON provider block such as `azure: { subscriptionKey, endpoint }`, `aws: { region, formality }`, or `google: { apiKey, model }`. Flat inputs below still work and override values inside the block. | no | — |
| subscriptionKey | Azure AI Translator resource subscription key. Required when provider is 'azure'. Pass via secrets. | no | — |
| endpoint | Azure AI Translator resource endpoint (e.g. 'https://api.cognitive.microsofttranslator.com/'). Required when provider is 'azure'. | no | — |
| region | Azure AI Translator resource region (optional for global resources). | no | — |
| awsAccessKeyId | AWS access key id. Optional — when omitted (along with awsSecretAccessKey) the AWS SDK default credential chain is used (recommended: OIDC via aws-actions/configure-aws-credentials). Pass via secrets. | no | — |
| awsSecretAccessKey | AWS secret access key. Must be supplied together with awsAccessKeyId. Pass via secrets. | no | — |
| awsSessionToken | Optional AWS session token for temporary credentials. Pass via secrets. | no | — |
| awsRegion | AWS region for the Translate service (e.g. 'us-east-1'). Required when provider is 'aws' unless AWS_REGION is set in the environment (e.g. by aws-actions/configure-aws-credentials). | no | — |
| awsFormality | AWS Translate formality setting: 'FORMAL' or 'INFORMAL'. Optional; ignored by Azure and Google. | no | — |
| awsBrevity | When 'true', enables AWS Translate brevity mode for supported language pairs. Optional; ignored by Azure and Google. | no | — |
| awsTerminologyNames | Optional AWS Translate custom terminology resource names. Accepts a JSON array or comma-separated values. | no | — |
| awsParallelDataNames | Optional AWS Translate parallel data resource names. Accepts a JSON array or comma-separated values. | no | — |
| googleApiKey | Google Cloud API key. Provide this OR googleCredentials when provider is 'google'. Pass via secrets. | no | — |
| googleCredentials | Google Cloud service-account key as a JSON string. Provide this OR googleApiKey when provider is 'google'. Pass via secrets. | no | — |
| googleProjectId | Optional Google Cloud project id. Usually inferred from the service-account credentials. | no | — |
| googleModel | Optional Google Cloud Translation model, e.g. 'nmt' or 'base'. | no | — |
| googleApiEndpoint | Optional Google Cloud Translation API endpoint override. | no | — |
| googleAutoRetry | Optional Google Cloud Translation auto-retry toggle. When unset, the Google client default applies; use maxRetries to control retry count. | no | — |
| toLocales | Optional locales to translate to. Accepts a JSON array (`["es","de","fr"]`) or comma-separated values (`es,de,fr`). When omitted, every supported locale is targeted. | no | — |
| include | Optional newline-separated glob patterns to include. When set, only matching files are translated. | no | — |
| exclude | Optional newline-separated glob patterns to exclude. Applied after `include`. | no | — |
| configPath | Optional path to a YAML config file (defaults to `.github/resource-translator.yml`). Repository config keys are merged underneath the action inputs. | no | .github/resource-translator.yml |
| categoryId | Optional Azure AI Translator Custom Translator category ID. Azure-only; ignored by the aws and google providers. | no | — |
| apiVersion | Translator API version. Defaults to '3.0'. Azure-only; ignored by the aws and google providers. | no | — |
| textType | Text type — 'plain' (default) or 'html'. Use 'html' only when resource values contain real HTML fragments. Mapped for azure (textType) and google (format); ignored by aws (no plain/html toggle). | no | — |
| profanityAction | How to handle profanity in translations: 'NoAction' (default), 'Marked', or 'Deleted'. Azure honors all values; aws maps 'Marked'/'Deleted' to masking; google has no equivalent and ignores it. | no | — |
| profanityMarker | How to mark profanity when 'profanityAction' is 'Marked': 'Asterisk' (default) or 'Tag'. Azure-only. | no | — |
| allowFallback | When 'false', Translator returns an error instead of falling back to the general system if the chosen 'categoryId' has no deployment for a target locale. Defaults to the Translator default (true) when unset. Azure-only. | no | — |
| noTranslatePatterns | Optional newline-separated glob patterns matched against parser key paths (resx 'name', po 'msgid', xliff unit 'id', '[--]'-joined paths for json, raw key for ini/restext). Matching keys are kept verbatim and never sent to Translator. | no | — |
| changeDetection | Smart change detection mode. Defaults to 'smart', which uses a deterministic state manifest to translate only changed/missing keys. Set to 'disabled' (or 'false') to translate every eligible key on every run. | no | — |
| statePath | Path to the deterministic smart change-detection state manifest, relative to the workspace root unless absolute. | no | — |
| protectPlaceholders | When 'true' (default), wrap '{{name}}', '{0}', '%s', '${var}', etc. in stable sentinels so Translator does not rearrange or translate them. Set to 'false' only if your source contains literal placeholder-like sequences. | no | — |
| customPlaceholderPatterns | Optional newline-separated regex patterns appended to the placeholder protector. Each pattern is compiled with the global flag if it does not start with a literal '/'. Invalid patterns are skipped. | no | — |
| maxRetries | Number of additional attempts on transient Translator failures (HTTP 408, 425, 429, 500, 502, 503, 504). Total HTTP calls per request = 1 + maxRetries. Defaults to 5. | no | — |
| retryBackoffMs | Cap (ms) on any single backoff sleep between retries. Translator's 'Retry-After' header is honored exactly when present; otherwise a jittered exponential sleep is used, capped at this value. Defaults to 30000. | no | — |
| dryRun | When 'true', perform translations and emit summary outputs but do not write files. | no | false |
| snapshotOnly | When 'true', bootstrap/update the smart change-detection state manifest from existing source and target files without calling a translation provider or writing target resource files. Useful for seeding .github/resource-translator-state.json before enabling normal incremental runs. | no | false |
| failOnError | When 'true' (default), unexpected errors fail the action. When 'false', errors are logged as warnings. | no | true |
Outputs
| name | description |
|---|---|
| summary-title | A short summary suitable for a PR title (e.g. "Machine-translated 320 files, a total of 5,418 translations"). |
| summary-details | A markdown summary, suitable for a PR body or job summary. |
| has-new-translations | Boolean as string. 'true' when one or more new translations were generated. |