intlayer: Pacchetto NPM per Gestire Dizionari Multilingue (i18n)

Intlayer è una suite di pacchetti progettata specificamente per sviluppatori JavaScript. È compatibile con framework come React, Next.js ed Express.js.

Il pacchetto intlayer ti permette di dichiarare il tuo contenuto ovunque nel tuo codice. Converte le dichiarazioni di contenuti multilingue in dizionari strutturati che si integrano perfettamente nella tua applicazione. Con TypeScript, Intlayer migliora il tuo sviluppo fornendo strumenti più potenti ed efficienti.

Perché integrare Intlayer?

• Gestione dei contenuti basata su JavaScript: Sfrutta la flessibilità di JavaScript per definire e gestire i tuoi contenuti in modo efficiente.
• Ambiente Type-Safe: Usa TypeScript per garantire che tutte le definizioni dei tuoi contenuti siano precise e prive di errori.
• File di contenuto integrati: Mantieni le tue traduzioni vicine ai rispettivi componenti, migliorando la manutenibilità e la chiarezza.

Installazione

Installa il pacchetto necessario utilizzando il gestore di pacchetti che preferisci:

npm install intlayer

Configura Intlayer

Intlayer fornisce un file di configurazione per impostare il tuo progetto. Posiziona questo file nella radice del tuo progetto.

import { Locales, type IntlayerConfig } from "intlayer";const config: IntlayerConfig = {  internationalization: {    locales: [Locales.ENGLISH, Locales.FRENCH, Locales.SPANISH],    defaultLocale: Locales.ENGLISH,  },};export default config;

Per un elenco completo dei parametri disponibili, consulta la documentazione di configurazione.

Esempio di utilizzo

Con Intlayer, puoi dichiarare i tuoi contenuti in modo strutturato ovunque nel tuo codice.

Per impostazione predefinita, Intlayer esegue la scansione dei file con estensione .content.{json,ts,tsx,js,jsx,mjs,mjx,cjs,cjx}.

Puoi modificare l'estensione predefinita impostando la proprietà contentDir nel file di configurazione.

.├── intlayer.config.ts└── src    ├── ClientComponent    │   ├── index.content.ts    │   └── index.tsx    └── ServerComponent        ├── index.content.ts        └── index.tsx

Dichiara i tuoi contenuti

Ecco un esempio di dichiarazione dei contenuti:

import { t, type Dictionary } from "intlayer";const clientComponentContent = {  key: "client-component",  content: {    myTranslatedContent: t({      en: "Hello World",      es: "Hola Mundo",      fr: "Bonjour le monde",    }),    numberOfCar: enu({      "<-1": "Less than minus one car",      "-1": "Minus one car",      "0": "No cars",      "1": "One car",      ">5": "Some cars",      ">19": "Molte auto",    }),  },} satisfies Dictionary;export default clientComponentContent;

Costruisci i tuoi dizionari

Puoi costruire i tuoi dizionari usando il intlayer-cli.

npx intlayer dictionaries build

Questo comando esegue la scansione di tutti i file *.content.*, li compila e scrive i risultati nella directory specificata nel tuo intlayer.config.ts (di default, ./.intlayer).

Un output tipico potrebbe apparire così:

.└── .intlayer    ├── dictionary  # Contiene il dizionario del tuo contenuto    │   ├── client-component.json    │   └── server-component.json    ├── main  # Contiene il punto di ingresso del tuo dizionario da utilizzare nella tua applicazione    │   ├── dictionary.cjs    │   └── dictionary.mjs    └── types  # Contiene le definizioni di tipo generate automaticamente per il tuo dizionario        ├── intlayer.d.ts  # Contiene le definizioni di tipo generate automaticamente per Intlayer        ├── client-component.d.ts        └── server-component.d.ts

Costruire le risorse i18next

Intlayer può essere configurato per creare dizionari per i18next. Per farlo, è necessario aggiungere la seguente configurazione al file intlayer.config.ts:

import { Locales, type IntlayerConfig } from "intlayer";const config: IntlayerConfig = {  /* ... */  content: {    // Indica a Intlayer di generare i file dei messaggi per i18next    dictionaryOutput: ["i18next"],    // La directory in cui Intlayer scriverà i file JSON dei messaggi    i18nextResourcesDir: "./i18next/resources",  },};

Per un elenco completo dei parametri disponibili, fare riferimento alla documentazione di configurazione.

Output:

.└── i18next    └── resources        ├── en        │   ├── client-component.json        │   └── server-component.json        ├── es        │   ├── client-component.json        │   └── server-component.json        └── fr            ├── client-component.json            └── server-component.json

Ad esempio, il file en/client-component.json potrebbe apparire così:

{  "myTranslatedContent": "Hello World",  "zero_numberOfCar": "No cars",  "one_numberOfCar": "One car",  "two_numberOfCar": "Two cars",  "other_numberOfCar": "Alcune auto"}

Costruire dizionari next-intl

Intlayer può essere configurato per costruire dizionari per i18next o next-intl. Per questo è necessario aggiungere la seguente configurazione nel file intlayer.config.ts:

import { Locales, type IntlayerConfig } from "intlayer";const config: IntlayerConfig = {  /* ... */  content: {    // Indica a Intlayer di generare file di messaggi per i18next    dictionaryOutput: ["next-intl"],    // La directory in cui Intlayer scriverà i file JSON dei messaggi    nextIntlMessagesDir: "./i18next/messages",  },};

Per un elenco completo dei parametri disponibili, fare riferimento alla documentazione di configurazione.

Output:

.└── intl    └── messages        ├── en        │   ├── client-component.json        │   └── server-component.json        ├── es        │   ├── client-component.json        │   └── server-component.json        └── fr            ├── client-component.json            └── server-component.json

Ad esempio, il file en/client-component.json potrebbe essere simile a:

{  "myTranslatedContent": "Ciao Mondo",  "zero_numberOfCar": "Nessuna macchina",  "one_numberOfCar": "Una macchina",  "two_numberOfCar": "Due macchine",  "other_numberOfCar": "Alcune macchine"}

Strumenti CLI

Intlayer fornisce uno strumento CLI per:

• verificare le tue dichiarazioni di contenuto e completare le traduzioni mancanti
• costruire dizionari dalle tue dichiarazioni di contenuto
• inviare e recuperare dizionari remoti dal tuo CMS al progetto locale

Consulta intlayer-cli per maggiori informazioni.

Usare Intlayer nella tua applicazione

Una volta dichiarato il tuo contenuto, puoi utilizzare i dizionari Intlayer nella tua applicazione.

Intlayer è disponibile come pacchetto per la tua applicazione.

Applicazione React

Per usare Intlayer nella tua applicazione React, puoi utilizzare react-intlayer.

Applicazione Next.js

Per usare Intlayer nella tua applicazione Next.js, puoi utilizzare next-intlayer.

Applicazione Express

Per usare Intlayer nella tua applicazione Express, puoi utilizzare express-intlayer.

Funzioni fornite dal pacchetto intlayer

Il pacchetto intlayer fornisce anche alcune funzioni per aiutarti a internazionalizzare la tua applicazione.

• getConfiguration()
• getTranslation()
• getEnumeration()
• getLocaleName()
• getLocaleLang()
• getHTMLTextDir()
• getPathWithoutLocale()
• getMultilingualUrls()
• getLocalizedUrl()
• getPathWithoutLocale()

Cronologia della documentazione

• 5.5.10 - 2025-06-29: Inizializzazione della cronologia