action.yml

name: 'Machine Translator'
description: 'Automatically open machine-translated pull requests for resource files using Azure, AWS, or Google translation providers. Supports .resx, .restext, .ini, .xliff, .po, and .json.'
author: 'David Pine'
branding:
  icon: flag
  color: blue
inputs:
  sourceLocale:
    description: "Source locale (e.g. 'en') used to find translation files (e.g. **/*.en.resx)."
    required: true
  provider:
    description: "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."
    required: false
  # --- Azure AI Translator (provider: azure — the default) ---
  subscriptionKey:
    description: "Azure AI Translator resource subscription key. Required when provider is 'azure'. Pass via secrets."
    required: false
  endpoint:
    description: "Azure AI Translator resource endpoint (e.g. 'https://api.cognitive.microsofttranslator.com/'). Required when provider is 'azure'."
    required: false
  region:
    description: 'Azure AI Translator resource region (optional for global resources).'
    required: false
  # --- AWS Translate (provider: aws) ---
  awsAccessKeyId:
    description: "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."
    required: false
  awsSecretAccessKey:
    description: 'AWS secret access key. Must be supplied together with awsAccessKeyId. Pass via secrets.'
    required: false
  awsSessionToken:
    description: 'Optional AWS session token for temporary credentials. Pass via secrets.'
    required: false
  awsRegion:
    description: "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)."
    required: false
  awsFormality:
    description: "AWS Translate formality setting: 'FORMAL' or 'INFORMAL'. Optional; ignored by Azure and Google."
    required: false
  awsBrevity:
    description: "When 'true', enables AWS Translate brevity mode for supported language pairs. Optional; ignored by Azure and Google."
    required: false
  awsTerminologyNames:
    description: 'Optional AWS Translate custom terminology resource names. Accepts a JSON array or comma-separated values.'
    required: false
  awsParallelDataNames:
    description: 'Optional AWS Translate parallel data resource names. Accepts a JSON array or comma-separated values.'
    required: false
  # --- Google Cloud Translation v2 (provider: google) ---
  googleApiKey:
    description: "Google Cloud API key. Provide this OR googleCredentials when provider is 'google'. Pass via secrets."
    required: false
  googleCredentials:
    description: "Google Cloud service-account key as a JSON string. Provide this OR googleApiKey when provider is 'google'. Pass via secrets."
    required: false
  googleProjectId:
    description: 'Optional Google Cloud project id. Usually inferred from the service-account credentials.'
    required: false
  googleModel:
    description: "Optional Google Cloud Translation model, e.g. 'nmt' or 'base'."
    required: false
  googleApiEndpoint:
    description: 'Optional Google Cloud Translation API endpoint override.'
    required: false
  googleAutoRetry:
    description: "Optional Google Cloud Translation auto-retry toggle. When unset, the Google client default applies; use maxRetries to control retry count."
    required: false
  toLocales:
    description: '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.'
    required: false
  include:
    description: 'Optional newline-separated glob patterns to include. When set, only matching files are translated.'
    required: false
  exclude:
    description: 'Optional newline-separated glob patterns to exclude. Applied after `include`.'
    required: false
  configPath:
    description: 'Optional path to a YAML config file (defaults to `.github/resource-translator.yml`). Repository config keys are merged underneath the action inputs.'
    required: false
    default: '.github/resource-translator.yml'
  categoryId:
    description: 'Optional Azure AI Translator Custom Translator category ID. Azure-only; ignored by the aws and google providers.'
    required: false
  apiVersion:
    description: "Translator API version. Defaults to '3.0'. Azure-only; ignored by the aws and google providers."
    required: false
  textType:
    description: "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)."
    required: false
  profanityAction:
    description: "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."
    required: false
  profanityMarker:
    description: "How to mark profanity when 'profanityAction' is 'Marked': 'Asterisk' (default) or 'Tag'. Azure-only."
    required: false
  allowFallback:
    description: "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."
    required: false
  noTranslatePatterns:
    description: "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."
    required: false
  changeDetection:
    description: "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."
    required: false
  statePath:
    description: "Path to the deterministic smart change-detection state manifest, relative to the workspace root unless absolute."
    required: false
  protectPlaceholders:
    description: "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."
    required: false
  customPlaceholderPatterns:
    description: "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."
    required: false
  maxRetries:
    description: "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."
    required: false
  retryBackoffMs:
    description: "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."
    required: false
  dryRun:
    description: "When 'true', perform translations and emit summary outputs but do not write files."
    required: false
    default: 'false'
  snapshotOnly:
    description: "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."
    required: false
    default: 'false'
  failOnError:
    description: "When 'true' (default), unexpected errors fail the action. When 'false', errors are logged as warnings."
    required: false
    default: 'true'
outputs:
  summary-title:
    description: 'A short summary suitable for a PR title (e.g. "Machine-translated 320 files, a total of 5,418 translations").'
  summary-details:
    description: 'A markdown summary, suitable for a PR body or job summary.'
  has-new-translations:
    description: "Boolean as string. 'true' when one or more new translations were generated."
runs:
  using: 'node24'
  main: 'dist/resource-translator/index.js'