So übersetzt du eine JSON-Datei in eine andere Sprache

Um eine JSON-Sprachdatei zu übersetzen, lade die Quelldatei hoch, gib die Zielsprache an und übersetze die Textwerte. Beginne mit einer kleinen Datei im kostenlosen JSON-Übersetzer und prüfe die zurückgegebene Datei anschließend in deiner App. Du kannst das hier verwendete Beispiel herunterladen.

Diese Anleitung richtet sich an App-Texte, zum Beispiel in locales/en.json. Wenn deine Datei einen Produktkatalog oder API-Datensätze enthält, lege fest, welche Felder lesbare Texte enthalten, bevor du denselben Ablauf verwendest. Eine als Zeichenfolge gespeicherte Kennung bleibt eine Kennung.

Teste zuerst diese sechs Zeichenfolgen

Das Beispiel enthält einen Checkout-Bildschirm und zwei Beschriftungen für Einstellungen:

{
  "checkout": {
    "title": "Your order",
    "greeting": "Hello, {{name}}",
    "pay": "Pay now",
    "support": "Contact Pinecart support"
  },
  "settings": {
    "language": "Language",
    "notifications": "Email notifications"
  }
}

Lade die Datei in das JSON-Tool hoch und gib Folgendes ein:

Translate every text value into French.
Keep Pinecart in English and preserve {{name}} exactly.

Das kostenlose Tool verarbeitet Dateien bis zu 2 MB, maximal fünf pro Tag, und übersetzt bis zu 5.000 Wörter pro Datei. Größere Dateien werden vollständig zurückgegeben, wobei der restliche Text unverändert bleibt. Der Download eignet sich damit als Beispiel, ist aber keine vollständig übersetzte Sprachdatei. Verwende die App, wenn du eine große Datei vollständig übersetzen, ein Glossar für deinen Arbeitsbereich nutzen oder wiederkehrende Releases bearbeiten möchtest.

Welche Teile zu deiner App gehören

Die Anwendung greift auf checkout.title zu. Nutzer sehen den zugehörigen Wert. Die Namensvariable wird zur Laufzeit eingesetzt. Bei einem Sprachwechsel müssen beide erhalten bleiben.

AI Glot liest JSON als Struktur ein und schreibt es mit zwei Leerzeichen Einrückung zurück. Ein Diff kann deshalb auch Änderungen an Leerzeichen enthalten. Prüfe die Werte unabhängig von der Formatierung.

Lege deine Platzhalterkonvention fest. Das Beispiel verwendet die i18next-ähnliche Schreibweise {{name}}. Andere Projekte verwenden {name}, %s oder ICU-Nachrichten. Kopiere beim Formulieren der Anweisung einen echten String aus deiner App. Wandle beim Übersetzen nicht eine Konvention in eine andere um.

Prüfe den Plan vor einem umfangreichen Auftrag

Verwende bei regelmäßigen Releases ein Workspace-Glossar für Produktbegriffe und Funktionsnamen. Die Umfangsanweisungen legen fest, welche Werte übersetzt werden. Die Formulierungsregeln bestimmen, wie jeder Wert geschrieben wird.

Eine reine Quelldatei wie en.json verrät nicht, welche französischen Bezeichnungen letzten Monat übersetzt wurden. Die Aufforderung, „nur die fehlenden französischen Zeichenfolgen zu übersetzen“, hilft nicht weiter, wenn keine französische Datei zum Vergleichen vorliegt. Schließe bekannte Schlüsselpräfixe aus oder stelle Quell- und Zielfelder gemeinsam bereit und prüfe, wie der Plan die Anweisung interpretiert. Der Leitfaden zu Sprachdateien für Apps behandelt den umfassenderen Workflow und weitere Formate.

Führe vor dem Commit eine Strukturprüfung durch

Speichere den Download neben en.json als fr.json. Kopiere den folgenden Code in check-locale.mjs und führe mit Node.js node check-locale.mjs aus. Das Skript prüft verschachtelte Objektschlüssel, Array-Längen, Werttypen, unveränderte Nicht-Textwerte und die doppelten geschweiften Klammern der Platzhalter im Beispiel.

import { readFileSync } from 'node:fs';
import assert from 'node:assert/strict';

const source = JSON.parse(readFileSync('en.json', 'utf8'));
const target = JSON.parse(readFileSync('fr.json', 'utf8'));
const tokens = text => [...text.matchAll(/\{\{[^{}]+\}\}/g)]
  .map(match => match[0]).sort();

function check(a, b, path = '$') {
  assert.equal(typeof b, typeof a, `${path}: value type changed`);
  if (a === null || typeof a !== 'object') {
    if (typeof a === 'string') {
      assert.ok(b.trim().length || !a.trim().length,
        `${path}: translation is empty`);
      assert.deepEqual(tokens(b), tokens(a),
        `${path}: placeholders changed`);
    } else {
      assert.deepEqual(b, a, `${path}: non-text value changed`);
    }
    return;
  }
  assert.equal(Array.isArray(b), Array.isArray(a),
    `${path}: container type changed`);
  assert.ok(b !== null, `${path}: container is null`);
  if (Array.isArray(a)) {
    assert.equal(b.length, a.length, `${path}: array length changed`);
  }
  assert.deepEqual(Object.keys(b).sort(), Object.keys(a).sort(),
    `${path}: keys changed`);
  for (const key of Object.keys(a)) check(a[key], b[key], `${path}.${key}`);
}

check(source, target);
console.log('Keys, types and {{placeholders}} match. Review the wording next.');

Damit wird ein Vertrag geprüft, nicht die Übersetzungsqualität. Auch ein auf Englisch belassener Wert besteht die Prüfung. Ebenso eine grammatikalisch falsche Übersetzung oder ein Text, der für die Schaltfläche zu lang ist. Die Token-Regel deckt {{name}} ab, aber nicht jedes Platzhalterformat. Passe sie an die Syntax deiner Anwendung an.

Bei i18next JSON v4 verwenden Pluralvarianten sprachspezifische Suffixe, und deine Aufrufe übergeben eine Anzahl. Bereite die Schlüssel vor, die dein Ziellocale benötigt, und teste sie. Diese Prüfung auf Schlüsselgleichheit lehnt eine geänderte Schlüsselmenge bewusst ab. Sie erzeugt oder validiert keinen neuen Pluralbestand.

In der Anwendung abschließen

Verweise den vorhandenen französischen Locale-Loader deiner App auf fr.json. Öffne den Checkout, setze einen echten Namen ein und prüfe die längste Schaltflächenbeschriftung bei der kleinsten unterstützten Bildschirmbreite. Wenn du Pluralformen verwendest, teste Anzahlen, die jede Form der Zielsprache abdecken.

Bei einer kleinen Datei reicht eine sorgfältige manuelle Prüfung möglicherweise aus. Bei Tausenden von Strings in jedem Release sollten Quelldatei, Glossar, diese Strukturprüfung und die UI-Prüfung Teil desselben Workflows sein. Die App-Lokalisierungslösung erklärt, wie AI Glot in den Prozess passt, wenn mehrere Personen ihn pflegen.