Configuration · Traducteur de ressources

Écrase le chemin avec l’entrée configPath si tu as besoin d’un emplacement non par défaut.

Schéma

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

Référence de terrain

provider

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

Type: string

Ça revient à l’entrée sourceLocale si ce n’est pas réglé. C’est aussi transféré vers le traducteur comme from=<locale> pour que les courtes chaînes ne soient pas détectées automatiquement.

toLocales

Type: string[]

Soit un tableau, soit une chaîne séparée par des virgules.

include / exclude

Type: string[]

Les motifs glob sont évalués par rapport aux chemins absolus et relatifs à l’espace de travail.

glossary

Type: map<string,string>

Les dérogations de termes post-traduction. Conscient des frontières de mots (gère C++, .NET).

categoryId

Type: string

Azure Custom Translator catégorie — votre industrie/domaine (légal, médical, ton marketing, etc.). Envoyé comme ?category=....

textType

Type: "plain" | "html"

Par défaut, c’est plain. Utilisez html seulement si vos valeurs de ressources contiennent de vrais fragments HTML.

profanityAction

Type: "NoAction" | "Marked" | "Deleted"

Comment traiter les termes profanes dans des résultats traduits.

profanityMarker

Type: "Asterisk" | "Tag"

Seulement quand profanityAction est "Marked".

allowFallback

Type: boolean

Réglez sur false pour échouer la traduction lorsque votre categoryId n’a pas de déploiement pour un lieu cible, au lieu de revenir au modèle général.

apiVersion

Type: string

Version de l’API REST du traducteur. Par défaut, c’est 3.0.

awsFormality

Type: "FORMAL" | "INFORMAL"

AWS Translate formality setting for supported target languages.

awsBrevity

Type: boolean

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

awsTerminologyNames / awsParallelDataNames

Type: string[]

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

googleModel

Type: string

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

googleApiEndpoint

Type: string

Optional Google Cloud Translation API endpoint override.

googleAutoRetry

Type: boolean

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

maxRetries

Type: integer

Tentatives maximales sur les réponses HTTP transitoires (408, 425, 429, 500, 502, 503, 504). Par défaut, c’est 5. Le nombre total d’appels HTTP par requête est 1 + maxRetries.

retryBackoffMs

Type: integer

Limite (ms) pour chaque sommeil en recul. Par défaut, c’est 30000. L’en-tête Retry-After d’Azure est honoré exactement lorsqu’il est présent; sinon, un reculement exponentiel gigoté est utilisé, plafonné à cette valeur.

protectPlaceholders

Type: boolean

Par défaut, c’est true. Lorsqu’ils sont activés, des jetons comme {{name}}, ${var}, {0}, {0:N2}, %s, %1$s et HTML sont remplacés par des jetons sentinelle avant la traduction et restaurés ensuite. Désactivez seulement lorsque la source contient intentionnellement des littéraux en forme de placeholder.

customPlaceholderPatterns

Type: string[]

Des motifs regex supplémentaires (sans délimiteurs) ajoutés à l’ensemble réservé par défaut, par exemple <<.+?>> pour une syntaxe personnalisée des jetons. Les regex invalides sont ignorés.

noTranslatePatterns

Type: string[]

Les motifs glob correspondaient aux clés de niveau analyseur (chemin pointillé JSON, name RESX, msgid PO, id d’unité XLIFF, clé INI/restext). Les clés correspondantes sont retirées de la requête et passent en conservant leur valeur source.

changeDetection

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

Type: string

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

Ordre de chargement

L’action lit des entrées explicites du flux de travail.
Il charge la configuration YAML depuis configPath.
Pour chaque champ partagé, l’entrée l’emporte; sinon, la valeur YAML est utilisée.
Les valeurs fusionnées sont validées. Les enums invalides (par exemple profanityAction: Mask) font échouer rapidement l’action avec un message clair.

Ton et industrie, en termes simples

L’API Azure AI Translator v3 ne possède pas un seul bouton de tonalité. Deux réglages combinés offrent la plupart des mêmes contrôles :

Industrie / domaine : utilisez categoryId pour pointer une catégorie Azure Custom Translator entraînée selon votre propre corpus — juridique, technique, médical, marketing ou autre. C’est le levier le plus puissant pour le ton, la voix de marque et le vocabulaire.
Texte de surface : Utilisez le Glossaire pour verrouiller les noms de marques et les termes produits mot pour mot, et utilisez profanityAction pour éliminer les termes grossiers lorsqu’on cible la localisation auprès de jeunes publics.

Choisissez votre langue

Configuration du dépôt

Schéma

Référence de terrain

Ordre de chargement

Ton et industrie, en termes simples