Non dovete scegliere: i18next e inlang, insieme

Se usate i18next, l'ecosistema inlang vi è probabilmente stato presentato come una destinazione: migrare il setup, adottare un nuovo formato, cambiare flusso di lavoro. E così la maggior parte dei team i18next non ha mai toccato strumenti come l'estensione VS Code Sherlock, l'editor web Fink o il compilatore Paraglide, anche quando uno di essi sarebbe stato davvero utile.

Quell'aut-aut non è mai stato necessario. I vostri file di traduzione sono l'interfaccia: se gli strumenti inlang sanno leggere e scrivere fedelmente il JSON i18next, potete usare entrambi gli ecosistemi sullo stesso progetto. Da questa settimana possono farlo. Verificato, riparato dove era rotto, e a un solo comando di distanza:

npx i18next-cli init --inlang

Un comando, nessuna migrazione

init --inlang (nuovo in i18next-cli 1.63, proposto anche come domanda nel normale wizard init) genera un progetto inlang pronto all'uso accanto alla vostra configurazione i18next:

{
  "$schema": "https://inlang.com/schema/project-settings",
  "baseLocale": "en",
  "locales": ["en", "de", "fr", "it"],
  "modules": ["https://cdn.jsdelivr.net/npm/@inlang/plugin-i18next@6.2.1/dist/index.js"],
  "plugin.inlang.i18next": {
    "pathPattern": {
      "common": "./public/locales/{locale}/common.json",
      "app": "./public/locales/{locale}/app.json"
    }
  }
}

Tutto è derivato da ciò che i18next-cli sa già: baseLocale e locales dalla configurazione, il pathPattern dalla struttura del vostro extract.output, inclusa la forma a namespace, con i nomi dei namespace individuati dai file esistenti della lingua principale. Il comando aggiunge inoltre l'estensione Sherlock alle raccomandazioni di .vscode/extensions.json (merge rispettoso dei commenti, senza sovrascrivere nulla) e non sovrascrive mai un project.inlang/settings.json esistente.

La parte importante è ciò che non fa: nessuna conversione, nessun export, nessun secondo catalogo che inizia a divergere dal momento in cui viene creato. Il JSON i18next nel vostro repository resta l'unica fonte di verità.

Cosa sblocca

• Sherlock (VS Code): vedere e modificare le traduzioni inline dove le chiavi vengono usate, sui vostri file reali.
• Fink (browser): date un link a un traduttore; le modifiche finiscono nello stesso JSON via git.
• Paraglide (compilatore): compilare gli stessi file in funzioni di messaggio tree-shakable e completamente tipizzate, ad esempio per una nuova app SvelteKit o SolidStart accanto al vostro prodotto i18next esistente:

npx @inlang/paraglide-js compile --project ./project.inlang

import * as m from './src/paraglide/messages.js'

m['common:friend']({ count: 1, context: 'male' }) // "A boyfriend"

Plurali, contesto (da solo e combinato con i plurali), _zero, chiavi ordinali, namespace e formattazione {{count, number}} si comportano esattamente come i18next li definisce. Il motivo per cui possiamo affermarlo con serenità è spiegato più sotto.

Perché ora funziona: sei bug corretti in poche ore

Le promesse di "interoperabilità" costano poco, quindi abbiamo prima testato l'intero percorso end-to-end: JSON i18next v4 attraverso il plugin i18next di inlang, l'SDK e il compilatore Paraglide, più il percorso di scrittura di ritorno, perché strumenti di editing come Sherlock e Fink devono poter salvare.

Il nucleo ha retto bene, e le asperità erano reali. Sei bug tra plugin, SDK e compilatore: chiavi di contesto risolte silenziosamente sulla variante base, progetti con contesto impossibili da salvare, progetti a namespace che fallivano in scrittura, formattazione {{count, number}} persa in silenzio, _zero che non scattava mai con count: 0, e chiavi ordinali interpretate erroneamente come contesto.

Quello che è successo dopo è la parte che merita di essere raccontata: abbiamo segnalato tutti e sei i bug con riproduzioni, e Samuel Stroschein e il team inlang hanno sistemato la loro metà in poche ore, revisionato e mergiato le nostre correzioni del plugin altrettanto in fretta, e pubblicato tutto: @inlang/plugin-i18next 6.2.0, @inlang/sdk 2.10.0, @inlang/paraglide-js 2.19.0. Il plugin è mantenuto come cittadino di prima classe dal loro lato. Quell'impegno, più la velocità, rende un ponte costruito sopra di esso una scommessa sicura. Abbiamo poi riverificato la matrice di test completa contro i pacchetti pubblicati: 15/15 verde, con il plugin caricato dal CDN esattamente come lo caricherà il vostro progetto. Il team di inlang ha pubblicato un proprio annuncio dell'integrazione.

Lo schema si è ripetuto ancora una volta durante la stesura di questo articolo: lo screenshot di Sherlock qui sopra ha fatto emergere un settimo bug (Sherlock non mostrava silenziosamente alcuna annotazione per i progetti i18next, e da tempo). Segnalato con una correzione di una riga, mergiato e pubblicato come plugin 6.2.1 nel giro di poche ore. Lo screenshot mostra il comportamento corretto.

Dove si colloca Locize

Gli stessi file che Sherlock e Paraglide ora leggono sono i file che Locize sincronizza come vostro TMS gestito:

npx i18next-cli locize-sync

Così la divisione dei ruoli resta pulita. Gli sviluppatori lavorano nel repository, con Sherlock inline o con la compilazione Paraglide. I traduttori lavorano dove preferiscono: Fink per modifiche rapide basate su git, Locize per il flusso completo con fasi di revisione, traduzione automatica con punteggi di confidenza, memoria di traduzione, glossario, versioning e distribuzione CDN perché le correzioni vadano online senza redeploy. Un solo set di file, e ogni strumento lo legge e lo scrive direttamente.

Dettagli onesti

• La versione del plugin è fissata di proposito. Lo scaffold scrive @inlang/plugin-i18next@6.2.1, non un @6 flottante: jsDelivr serve gli alias di range da cache edge che possono restare indietro di giorni rispetto alle release e differire in base alla località. Abbiamo visto @6 servire un plugin vecchio di due release dopo l'uscita della 6.2.0. Un URL fissato significa che ogni membro del team e ogni esecuzione CI riceve lo stesso plugin, quello verificato. Aggiornate l'URL in modules dentro settings.json deliberatamente quando escono versioni nuove.
• Viene generato solo settings.json, di proposito. project.inlang/ è la forma di progetto unpacked (git-friendly) di inlang; gli strumenti inlang generano e gestiscono da soli gli altri file (.gitignore, README.md, cache/) al primo utilizzo. Aspettatevi quindi qualche file nuovo lì dopo aver aperto il progetto con Sherlock o Paraglide.
• I namespace vengono individuati al momento dello scaffold. Se in seguito aggiungete un namespace, aggiungete la sua riga al pathPattern in settings.json; una nuova esecuzione di init non tocca volutamente un file esistente.
• Solo file di risorse JSON. Il plugin i18next di inlang legge JSON; le strutture YAML/JS vengono saltate con un avviso.

Per iniziare

In un progetto con una configurazione i18next-cli (o lasciate che il wizard ne crei una):

npx i18next-cli init --inlang

Aprite la cartella in VS Code e installate l'estensione Sherlock raccomandata, mandate a un traduttore il link di Fink, oppure puntate il compilatore Paraglide su ./project.inlang. E continuate a sincronizzare esattamente gli stessi file con Locize per la parte gestita del flusso. Il riferimento completo delle opzioni è nel README di i18next-cli, e il plugin vive sul marketplace inlang.

Due ecosistemi, un solo set di file. Davvero, non dovete scegliere.