Traduire des documents

Importez des fichiers sources et des traductions précédentes, lancez une tâche de localisation et téléchargez les fichiers obtenus.

Les tâches de traduction de documents permettent de traduire des fichiers tout en conservant leur format. Une tâche peut regrouper plusieurs fichiers et langues cibles. L’API identifie chaque fichier par le hachage SHA-256 de sa séquence exacte d’octets.

Vous avez besoin d’une clé API, d’un identifiant d’organisation et d’un identifiant de moteur. Le guide de localisation des fichiers propose un exemple complet en Node.js.

Choisir un format #

Définissez format.type pour chaque document :

FormatType
JSON / JSONCjson / jsonc
Markdown / MDX / Markdocmd / mdx / markdoc
HTMLhtml
TypeScript / PHPtypescript / php
YAML / YAML avec langue à la racine / YAML OpenAPIyaml / yaml-root-key / yaml-openapi
Android / ARB Flutterandroid / flutter
Chaînes Apple / dictionnaires de pluriels / catalogues de chaînesxcode-strings / xcode-stringsdict / xcode-xcstrings
Gettext / XLIFF / SubRippo / xliff / srt
Texte bruttxt
Tableau CSV avec une colonne par languecsv
Propriétés Javaproperties
Contenu Payloadpayload

Les références des formats décrivent la structure des fichiers et les paramètres de contrôle. L’API format.options utilise le contrat de document ; la configuration de la CLI adapte ses propres noms d’options à ce contrat. Par exemple, l’API utilise frontmatterFields pour Markdown et componentProps pour les propriétés des composants. Les sélecteurs de clés JSON utilisent JSONPath.

Définir les options du format #

Vous pouvez omettre format.options pour utiliser les valeurs par défaut. Ne définissez que les options prises en charge par le type sélectionné :

TypeOptions
json, jsoncOptions JSON : règles de clés, périmètres, contexte, indications et injection de la langue.
typescript, php, yaml, yaml-root-keylockedKeys, preservedKeys, ignoredKeys (par défaut : []) ; keyScope et termScope facultatifs, mais non vides s’ils sont fournis.
mdfrontmatterFields (par défaut : ["$.title", "$.description"]) ; termScope facultatif, mais non vide s’il est fourni.
mdx, markdocOptions Markdown, plus componentProps (par défaut : []).
htmlcomponentProps (par défaut : []), en plus des attributs traduisibles intégrés au gestionnaire.
xcode-stringsdictlockedKeys et preservedKeys (par défaut : []) ; termScope facultatif, mais non vide s’il est fourni.
flutter, xcode-strings, xcode-xcstrings, android, yaml-openapitermScope facultatif, mais non vide s’il est fourni.
csvkeyColumn facultatif : l’en-tête de la colonne des clés (par défaut : la première cellule d’en-tête).
propertieslockedKeys, preservedKeys, ignoredKeys ([] par défaut) et keyScope (facultatif, non vide), comparés à la clé complète sous forme de motifs à l’ancienne, ou de JSONPath lorsqu’un motif commence par $ ; termScope (facultatif, non vide) ; lockedPatterns ([] par défaut), des expressions régulières RE2 dont les correspondances restent non traduites dans les valeurs.
payload, po, xliff, srt, txtAucune option supplémentaire.

Les règles de clés, les périmètres de clés et les champs de métadonnées d’en-tête utilisent des requêtes JSONPath. termScope sélectionne les unités sources entières qui contiennent au moins l’un des termes fournis comme sous-chaîne, en respectant la casse ; "cat" peut correspondre à "catalog". Lorsqu’un format prend en charge à la fois keyScope et termScope, fournir les deux sélectionne leur intersection. Ces deux périmètres nécessitent des traductions existantes auxquelles fusionner le contenu. La sélection et la réutilisation dépendent du format, comme l’explique la section mises à jour incrémentales. Ces options de l’API diffèrent de la prise en charge du format --key par la CLI.

Une règle de propriété de composant contient props, un tableau non vide de noms de propriétés, et éventuellement components, un tableau non vide qui limite la règle aux composants nommés. Si vous omettez components, la règle s’applique à tous les composants. Pour MDX :

json
{
  "type": "mdx",
  "options": {
    "frontmatterFields": ["$.title", "$.description", "$.sidebar.label"],
    "componentProps": [{ "components": ["Callout"], "props": ["title"] }]
  }
}

Cela traduit les métadonnées d’en-tête sélectionnées et les titres littéraux Callout, ainsi que le texte du document. Consultez la référence du format pour en savoir plus sur le code protégé, les expressions et le comportement de reconstruction.

Créer la tâche avec les adresses des artefacts #

Calculez le hachage de la séquence exacte d’octets que vous comptez importer. En Node.js :

js
import { createHash } from "node:crypto";
import { readFile } from "node:fs/promises";

const bytes = await readFile("messages/en.json");
const address = createHash("sha256").update(bytes).digest("hex");

Créez une tâche en utilisant l’adresse obtenue comme source du document :

json
{
  "engineId": "YOUR_ENGINE_ID",
  "sourceLocale": "en",
  "targetLocales": ["de"],
  "documents": [
    {
      "key": "messages/en.json",
      "format": { "type": "json" },
      "source": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa"
    }
  ]
}

Remplacez l’adresse d’exemple par le hachage calculé. Enregistrez l’identifiant de tâche renvoyé. uploads répertorie les artefacts d’entrée absents du stockage ; il n’est pas nécessaire d’importer à nouveau le contenu déjà stocké.

Importer les octets et démarrer #

Pour chaque entrée uploads, envoyez une requête PUT authentifiée à son uploadUrl avec Content-Type: application/octet-stream et les octets d’origine dans le corps de la requête. Importez les sources et tous les fichiers précédents référencés avant de démarrer.

Chaque artefact est limité à 25 Mio. Si le hachage ne correspond pas, la réponse est ArtifactChecksumMismatch ; si le fichier est trop volumineux, la réponse est RequestBodyTooLarge. Modifier les fins de ligne d’un texte après avoir calculé son hachage et avant de l’importer change ses octets et fait échouer la vérification.

Appelez POST /v2/localization/jobs/:id/start une fois toutes les importations réussies. Les importations d’artefacts ne sont acceptées qu’avant le démarrage de la tâche. Consultez la progression de la tâche par langue cible, puis téléchargez les fichiers terminés à partir des URL renvoyées.

Mettre à jour un document existant #

Pour une mise à jour incrémentale, conservez trois éléments : la nouvelle source, la source précédente et la traduction actuelle pour chaque langue cible. Fournissez :

  • source : l’adresse de l’artefact de la nouvelle source.
  • previousSource : l’adresse de la source utilisée pour la révision précédente.
  • previousTranslations : une entrée { "locale": "de", "artifact": "..." } par traduction disponible.

Incluez les modifications manuelles effectuées localement dans les octets de la traduction cible précédente que vous fournissez. Le gestionnaire de format peut réutiliser le contenu inchangé et traduire le contenu modifié. Pour le JSON standard, omettre la source précédente empêche la réutilisation du contenu dont la source est inchangée. Les autres formats peuvent reprendre le contenu cible existant selon leurs propres règles de fusion. Conservez la version de référence complète lorsque vous devez distinguer une modification de la source d’un message inchangé.

Une requête à périmètre limité via keyScope ou termScope nécessite une traduction précédente pour chaque langue cible. JSON, JSONC, TypeScript et PHP régénèrent les chaînes sélectionnées, y compris celles dont les valeurs sources sont inchangées, puis les fusionnent dans la cible existante. YAML, YAML avec langue à la racine et YAML OpenAPI peuvent réutiliser le contenu sélectionné inchangé lorsqu’une source précédente est fournie. XCStrings peut réutiliser les valeurs cibles intégrées ou fournies, même sans source précédente. Une unité sélectionnée ne nécessite donc pas toujours un nouveau travail de traduction.

Fournissez au moteur la terminologie ou la règle souhaitée avant de demander une régénération, puis examinez la traduction cible obtenue. Pour obtenir une formulation exacte, modifiez directement la cible : vous éviterez ainsi de dépendre de la régénération pour produire une phrase précise.

Avant de créer une tâche ultérieure, stockez une version de référence à l’aide de PUT /v2/organizations/:orgId/localization/artifacts/:address, en envoyant une requête authentifiée avec les octets du fichier dans son corps. Cette route nécessite un accès à la traduction via un moteur de l’organisation et renvoie les métadonnées de l’artefact. La même limite de 25 Mio et les mêmes vérifications de hachage s’appliquent.

Téléchargez d’abord les résultats dans des fichiers temporaires. Avant de remplacer les fichiers de l’application, comparez ces résultats à la révision source envoyée et aux éventuelles modifications de la cible effectuées depuis l’envoi. Préserver les traductions relues explique le workflow correspondant dans la CLI.