Configurazione · Traduttore di risorse

Sovrascrivi il percorso con l'input configPath se ti serve una posizione non predefinita.

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.*"

Riferimento sul campo

provider

Tipo: "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

Tipo: string

Torna all'input sourceLocale se non è impostato. È anche inoltrato a Translator come from=<locale> così le stringhe corte non vengono rilevate automaticamente.

toLocales

Tipo: string[]

O un array o una stringa separata da virgole.

include / exclude

Tipo: string[]

Modelli glob valutati rispetto a percorsi assoluti e relativi allo spazio di lavoro.

glossary

Tipo: map<string,string>

Sovrascritti dei termini post-traduzione. Consapevole del confine delle parole (gestisce C++, .NET).

categoryId

Tipo: string

Azure Custom Translator categoria — la tua manopola di industria/dominio (legale, medico, tono marketing, ecc.). Inviato come ?category=....

textType

Tipo: "plain" | "html"

Di default è plain. Usa html solo se i valori delle tue risorse contengono frammenti HTML reali.

profanityAction

Tipo: "NoAction" | "Marked" | "Deleted"

Come trattare termini profani in output tradotti.

profanityMarker

Tipo: "Asterisk" | "Tag"

Significato solo quando profanityAction è "Marked".

allowFallback

Tipo: boolean

Impostato su false fallire la traduzione quando il tuo categoryId non ha un deployment per una località target invece di tornare al modello generale.

apiVersion

Tipo: string

Versione dell'API REST del traduttore. Di default è 3.0.

awsFormality

Tipo: "FORMAL" | "INFORMAL"

AWS Translate formality setting for supported target languages.

awsBrevity

Tipo: boolean

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

awsTerminologyNames / awsParallelDataNames

Tipo: string[]

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

googleModel

Tipo: string

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

googleApiEndpoint

Tipo: string

Optional Google Cloud Translation API endpoint override.

googleAutoRetry

Tipo: boolean

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

maxRetries

Tipo: integer

Tentativi massimi di ritentativi sulle risposte HTTP transitorie (408, 425, 429, 500, 502, 503, 504). Di default è 5. Il totale delle chiamate HTTP per richiesta è 1 + maxRetries.

retryBackoffMs

Tipo: integer

Limiti (ms) su qualsiasi singolo sonno di retrocesso. Di default è 30000. L'intestazione Retry-After di Azure viene onorata esattamente quando presente; altrimenti si usa un backoff esponenziale jittered, limitato a questo valore.

protectPlaceholders

Tipo: boolean

Di default è true. Quando sono attivi, token come {{name}}, ${var}, {0}, {0:N2}, %s, %1$s e HTML vengono sostituiti con token sentinella prima della traduzione e ripristinati successivamente. Disabilita solo quando la sorgente contiene intenzionalmente letterali a forma di segnaposto.

customPlaceholderPatterns

Tipo: string[]

Pattern regex extra (senza delimitatori) aggiunti al set segnaposto predefinito, ad esempio <<.+?>> per la sintassi personalizzata dei token. Le regex non valide vengono ignorate.

noTranslatePatterns

Tipo: string[]

I pattern glob si abbinavano alle chiavi a livello di parser (JSON doted path, RESX name, PO msgid, unità XLIFF id, chiave INI/restext). Le chiavi corrispondenti vengono eliminate dalla richiesta e passate mantenendo il loro valore sorgente.

changeDetection

Tipo: "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

Tipo: string

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

Ordine di carico

L'azione legge input espliciti dal flusso di lavoro.
Carica la configurazione YAML da configPath.
Per ogni campo condiviso, l'input vince; altrimenti viene utilizzato il valore YAML.
I valori uniti sono validati. Gli enum non validi (ad esempio profanityAction: Mask) fanno fallire rapidamente l'azione con un messaggio chiaro.

Tono e industria, in termini semplici

L'API Azure AI Translator v3 non ha una singola manopola di tono. Due impostazioni si combinano per darti quasi sempre lo stesso controllo:

Settore / dominio: usa categoryId per indicare una categoria Azure Custom Translator addestrata sul tuo corpus — legale, tecnico, medico, marketing o altro. Questa è la leva più forte per il tono, la voce del marchio e il vocabolario.
Testo superficiale: Usa il Glossario per bloccare nomi di marchi e termini di prodotto parola per parola, e usa profanityAction per eliminare termini volgari quando si mira alla localizzazione per un pubblico più giovane.

Scegli la tua lingua

Configurazione del repository

Schema

Riferimento sul campo

Ordine di carico

Tono e industria, in termini semplici