Configuration · Umusemuzi w'ibikoresho

Kanda kuri configPath ukoresheje uburyo bwo kugenzura niba ukeneye ahantu hadakwiye.

Schema

# .github/resource-translator.yml
sourceLocale: en

# Provider config can be nested. Keep secrets in workflow inputs; use repo
# config for non-secret defaults like region, model, formality, or category.
provider:
  azure:
    categoryId: my-custom-translator-category
    apiVersion: "3.0"
    allowFallback: true

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

# 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)

# 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

provider

Ubwoko: "azure" | "aws" | "google" | provider block

Either a provider string or a nested provider block (provider.azure, provider.aws, or provider.google). Prefer nested blocks for provider-specific settings; keep secrets in workflow inputs rather than committed config.

sourceLocale

Ubwoko: string

Reka dusubire ku murongo sourceLocale niba utarashyizweho. Ikindi ni uko n'abasemuzi b'ikinyamakuru Izuba Rirashe from=<locale> ku buryo nta n'umwe ugira icyo abivugaho.

toLocales

Ubwoko: string[]

Cyangwa umurongo cyangwa umugozi utandukanywa na koma.

include / exclude

Ubwoko: string[]

Ibipimo bya Glob byasuzumiwe ugereranyije n'inzira zuzuye n'iz'akazi.

glossary

Ubwoko: map<string,string>

Post-translation term overrides. Word-boundary aware (handles C++, .NET).

categoryId

Ubwoko: string

Azure Custom Translator category — your industry/domain knob (legal, medical, marketing tone, etc.). Sent as ?category=....

textType

Ubwoko: "plain" | "html"

Kudakora plain. Use html only if your resource values contain real HTML fragments.

profanityAction

Ubwoko: "NoAction" | "Marked" | "Deleted"

How to treat profane terms in translated output.

profanityMarker

Ubwoko: "Asterisk" | "Tag"

Only meaningful when profanityAction is "Marked".

allowFallback

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

Ubwoko: string

Translator REST API version. Kudakora 3.0.

awsFormality

Ubwoko: "FORMAL" | "INFORMAL"

AWS Translate formality setting for supported target languages.

awsBrevity

Ubwoko: boolean

Set to true to enable AWS Translate brevity mode for supported language pairs.

awsTerminologyNames / awsParallelDataNames

Ubwoko: string[]

AWS Translate custom terminology and parallel data resource names. Either an array or comma-separated string.

googleModel

Ubwoko: string

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

googleApiEndpoint

Ubwoko: string

Optional Google Cloud Translation API endpoint override.

googleAutoRetry

Ubwoko: boolean

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

maxRetries

Ubwoko: integer

Maximum retry attempts on transient HTTP responses (408, 425, 429, 500, 502, 503, 504). Kudakora 5. Total HTTP calls per request is 1 + maxRetries.

retryBackoffMs

Ubwoko: integer

Bye Bye Birdie (On Any Backoff Sleep) Kudakora 30000. Umutwe wa Retry-After wa Azure wubashywe neza igihe uhari; otherwise jittered exponential backoff is used, capped at this value.

protectPlaceholders

Ubwoko: boolean

Kudakora true. Iyo umaze guhindurwa, ibimenyetso nka {{name}}, ${var}, {0}, {0:N2}, %s, %1$s na HTML bisimbuzwa ibimenyetso bya sentinel mbere yo guhindurwa hanyuma bigasubizwa nyuma. Disable only when source intentionally contains placeholder-shaped literals.

customPlaceholderPatterns

Ubwoko: string[]

Ibishushanyo byinyongera bya regex (bidafite delimiters) byongerewe kuri seti ya placeholder ya mbere, urugero <<.+?>> kuri syntax ya token isanzwe. Invalid regexes are ignored.

noTranslatePatterns

Ubwoko: string[]

Ibishushanyo bya Glob bihujwe n'urufunguzo rwo ku rwego rwa parser (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.

changeDetection

Ubwoko: "smart" | "disabled"

Defaults to smart. Uses the committed state manifest to translate only changed or missing parser keys. Set to disabled or false to preserve the legacy always-translate behavior.

statePath

Ubwoko: string

Path to the deterministic smart change-detection state manifest. Defaults to .github/resource-translator-state.json.

Loading order

The action reads explicit inputs from the workflow.
It loads the YAML config from configPath.
Kuri buri murima uhuriweho, umusaruro utsinda; otherwise the YAML value is used.
Ibiciro by'ibicuruzwa byashyizweho byemewe. Invalid enums (e.g. profanityAction: Mask) cause the action to fail fast with a clear message.

Tone and industry, in plain terms

Azure AI Translator v3 API ntabwo ifite tone imwe. Ibice bibiri bihuriye hamwe biguha igice kinini cy'ubugenzuzi bumwe:

Industry / domain: Use categoryId to point at an Azure Custom Translator category trained on your own corpus — legal, technical, medical, marketing, or anything else. Iyi ni lever ikomeye cyane y'amajwi, ijwi ry'ikirango, n'amagambo.
Surface text: Use the Glossary to lock brand names and product terms verbatim, and use profanityAction to scrub profane terms when targeting localization for young audiences.

Hitamo ururimi rwawe

Imiterere y'ububiko

Schema

Field reference

Loading order

Tone and industry, in plain terms