Come tradurre un file JSON in un'altra lingua

Per tradurre un file delle lingue JSON, carica il file di origine, indica la lingua di destinazione e traduci i valori di testo. Inizia con un file piccolo nel traduttore JSON gratuito, poi controlla il file restituito nella tua app. Puoi scaricare l’esempio usato qui.

Questa guida è dedicata alle stringhe delle app, ad esempio locales/en.json. Se il file contiene un catalogo prodotti o record API, individua i campi con testo leggibile prima di applicare lo stesso flusso di lavoro. Un identificatore memorizzato come stringa resta comunque un identificatore.

Prova prima queste sei stringhe

L’esempio include una schermata di pagamento e due etichette delle impostazioni:

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

Carica il file nello strumento JSON e inserisci:

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

Lo strumento gratuito accetta file fino a 2 MB, per un massimo di cinque al giorno, e traduce fino a 5.000 parole per file. I file più grandi vengono restituiti integralmente, con il testo restante invariato. Il file scaricato è quindi utile come esempio, ma non è una versione completamente tradotta. Per tradurre un file grande per intero, usare un glossario condiviso e gestire release successive, usa l’app.

Scopri quali parti appartengono alla tua app

L’applicazione richiama checkout.title; chi legge vede il valore associato. La variabile del nome viene valorizzata in fase di esecuzione. Entrambi devono essere mantenuti quando si cambia lingua.

AI Glot interpreta il JSON come una struttura e lo riscrive con un’indentazione di due spazi. Una diff può quindi includere modifiche agli spazi bianchi. Esamina i valori separatamente dalla formattazione.

Specifica la convenzione usata per i placeholder. L’esempio usa la sintassi {{name}} di i18next. Altri progetti usano {name}, %s o messaggi ICU. Quando scrivi le istruzioni, copia una stringa reale della tua app. Non convertire una convenzione in un’altra durante la traduzione.

Controlla il piano prima di un’attività impegnativa

Per le release ricorrenti, usa un glossario dell’area di lavoro per i termini del prodotto e i nomi delle funzionalità. Le istruzioni sull’ambito stabiliscono quali valori tradurre; le regole di formulazione stabiliscono come scrivere ciascun valore.

Un file en.json che contiene solo il testo sorgente non indica quali etichette francesi sono state tradotte il mese scorso. Chiedere di «tradurre solo le stringhe francesi mancanti» non fornisce alcun file in francese con cui fare il confronto. Escludi i prefissi di chiave noti oppure prepara insieme i campi sorgente e di destinazione, quindi controlla come il piano interpreta le istruzioni. La guida ai file delle lingue dell’app illustra il flusso di lavoro più ampio e altri formati.

Esegui un controllo strutturale prima del commit

Salva il file scaricato come fr.json, accanto a en.json. Copia questo codice in check-locale.mjs ed esegui node check-locale.mjs con Node.js. Il controllo verifica le chiavi degli oggetti annidati, la lunghezza degli array, i tipi di valore, i valori non testuali invariati e i placeholder con doppie parentesi graffe dell’esempio.

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.');

Questo controllo convalida un contratto, non la qualità della traduzione. Anche un valore lasciato in inglese supera il controllo. Lo supera anche una traduzione grammaticalmente scorretta o troppo lunga per il pulsante. La regola sui token copre {{name}}, ma non tutti i formati di placeholder: adattala alla sintassi della tua applicazione.

Con i18next JSON v4, le varianti plurali usano suffissi specifici per lingua e le chiamate forniscono un conteggio. Prepara e testa le chiavi richieste dalla lingua di destinazione. Questo controllo di uguaglianza delle chiavi rifiuta deliberatamente ogni modifica all’insieme di chiavi: non genera né convalida un nuovo inventario delle forme plurali.

Completa la verifica nell’applicazione

Configura il loader della lingua francese già presente nell’app affinché usi fr.json. Apri il checkout, inserisci un nome reale e controlla il pulsante più lungo alla larghezza minima dello schermo supportata. Se usi i plurali, prova i conteggi che attivano ciascuna forma prevista nella lingua di destinazione.

Per un file piccolo, può bastare una revisione manuale accurata. Se a ogni rilascio devi gestire migliaia di stringhe, mantieni nello stesso flusso di lavoro il file sorgente, il glossario, questo controllo della struttura e la revisione dell’interfaccia. La soluzione per la localizzazione delle app spiega come si inserisce AI Glot quando più persone si occupano di questo processo.