Traduire du JSON

Soumettez un objet JSON avec du contexte, des indications et des chemins protégés, puis téléchargez ses traductions.

Envoyez un objet JSON directement dans une tâche de localisation lorsque votre application dispose déjà de la source en mémoire. Lingo.dev le stocke sous forme de document JSON et génère une sortie pour chaque langue cible.

Le guide de démarrage rapide propose un programme complet. Cette référence détaille les champs de requête propres au JSON.

Soumettre un document intégré #

Créez la tâche à l'adresse POST /v2/organizations/:orgId/localization/jobs avec une clé API dans X-API-Key et un Idempotency-Key stable pour cette soumission :

json
{
  "engineId": "YOUR_ENGINE_ID",
  "sourceLocale": "en",
  "targetLocales": ["de", "fr"],
  "documents": [
    {
      "key": "settings.json",
      "format": {
        "type": "json",
        "options": {
          "context": "Settings dialog in a team collaboration application",
          "hints": { "$.save": ["Button that saves the edited settings"] },
          "lockedKeys": ["$.productName"]
        }
      },
      "source": {
        "content": {
          "save": "Save changes",
          "cancel": "Cancel",
          "productName": "Acme"
        }
      }
    }
  ]
}

La source doit être un objet JSON. Elle peut contenir des objets et des tableaux imbriqués. Les valeurs terminales de type chaîne sont candidates à la traduction ; les nombres, les booléens et les valeurs null conservent leur type JSON. Protégez les identifiants de type chaîne, les noms de produits ou les URL qui doivent rester inchangés.

Les sources intégrées utilisent format.type: "json". Pour du JSONC ou un autre format de fichier, téléversez les octets du fichier.

Ajouter du contexte et sélectionner le contenu #

Placez les options JSON dans le format.options du document :

OptionEffet
contextTexte non vide décrivant la finalité du contenu ou le public auquel il s'adresse.
hintsRequêtes JSONPath associées à des tableaux non vides contenant des indications non vides. Les indications correspondantes se cumulent pour les chaînes sélectionnées. Par défaut : un objet vide.
lockedKeysCopier les valeurs source sélectionnées sans les traduire. Par défaut : [].
preservedKeysRéutiliser les valeurs sélectionnées de la cible précédente lorsqu'elles sont disponibles ; sinon, copier la source. Par défaut : [].
ignoredKeysSupprimer les valeurs sélectionnées de la sortie. Par défaut : [].
keyScopeRégénérer les chaînes sélectionnées par une liste non vide de requêtes JSONPath. Nécessite une traduction précédente pour chaque langue cible.
termScopeRégénérer les chaînes correspondant à une liste non vide de termes source. Nécessite une traduction précédente pour chaque langue cible.
injectLocaleÉcrire la langue cible à un emplacement JSONPath unique, par exemple $.meta.locale. Ce sous-arbre est protégé contre la traduction.

Utilisez JSONPath dans les requêtes API. $.title sélectionne une propriété à la racine ; $.nav.home sélectionne une propriété imbriquée ; $['nav.home'] sélectionne une clé littérale contenant un point ; $..productName sélectionne cette propriété à n'importe quelle profondeur. La sélection d'un objet ou d'un tableau inclut les chaînes qu'il contient à tous les niveaux. Les noms de clés seuls ne constituent pas des requêtes API valides.

Les règles de contrôle des clés sont appliquées avant la traduction. Les valeurs ignorées sont supprimées ; les valeurs source verrouillées ont priorité sur les valeurs cibles préservées. La sélection du périmètre ne permet pas de contourner ces règles. Consultez la référence du format JSON pour en savoir plus sur l'assemblage de la sortie et les messages ICU.

termScope recherche des sous-chaînes dans les chaînes source en respectant la casse. Tout terme de la liste peut sélectionner une chaîne : "cat" correspond aussi à "catalog", tandis que "login" ne correspond pas à "Login". La chaîne sélectionnée est régénérée dans son intégralité, et pas seulement le terme correspondant. Lorsque keyScope et termScope sont tous deux présents, une chaîne doit satisfaire les deux critères. Utilisez une sélection précise de clés JSONPath lorsqu'une sous-chaîne risquerait d'inclure des messages sans rapport.

Démarrer et lire le résultat #

Enregistrez le id renvoyé dans la réponse de création. Téléversez chaque entrée de uploads si cette tâche fait également référence à des fichiers précédents ou à d'autres documents, puis appelez POST /v2/localization/jobs/:id/start.

Lisez GET /v2/localization/jobs/:id et examinez le targets de chaque document. Une cible avec status._tag: "Completed" dispose d'un status.downloadUrl. Téléchargez le contenu de cette URL en utilisant la même authentification pour obtenir l'objet JSON. La réponse de la tâche elle-même contient l'état d'avancement et les adresses des artefacts, pas l'objet traduit.

Pour les mises à jour, soumettez les artefacts source et cible précédents comme indiqué dans mettre à jour un document existant. Conservez la nouvelle révision de la source avec l'identifiant de la tâche afin qu'un résultat reçu en retard ne puisse pas remplacer un contenu plus récent.