Introduzione all'internazionalizzazione (i18n) con Intlayer ed Express

express-intlayer è un potente middleware di internazionalizzazione (i18n) per applicazioni Express, progettato per rendere i tuoi servizi backend accessibili globalmente fornendo risposte localizzate in base alle preferenze del cliente.

Perché Internazionalizzare il Tuo Backend?

Internazionalizzare il tuo backend è essenziale per servire efficacemente un pubblico globale. Permette alla tua applicazione di fornire contenuti e messaggi nella lingua preferita di ogni utente. Questa capacità migliora l'esperienza utente e amplia la portata della tua applicazione rendendola più accessibile e rilevante per persone di diversi background linguistici.

Casi d'Uso Pratici

• Visualizzazione degli errori del backend nella lingua dell'utente: Quando si verifica un errore, visualizzare i messaggi nella lingua madre dell'utente migliora la comprensione e riduce la frustrazione. Questo è particolarmente utile per messaggi di errore dinamici che potrebbero essere mostrati in componenti front-end come toast o modali.

• Recupero di contenuti multilingue: Per applicazioni che estraggono contenuti da un database, l'internazionalizzazione garantisce che tu possa fornire questi contenuti in più lingue. Questo è cruciale per piattaforme come siti di e-commerce o sistemi di gestione dei contenuti che devono mostrare descrizioni di prodotti, articoli e altri contenuti nella lingua preferita dall'utente.

• Invio di Email Multilingue: Che si tratti di email transazionali, campagne di marketing o notifiche, inviare email nella lingua del destinatario può aumentare significativamente il coinvolgimento e l'efficacia.

• Notifiche Push Multilingue: Per applicazioni mobili, inviare notifiche push nella lingua preferita dell'utente può migliorare l'interazione e la fidelizzazione. Questo tocco personale può rendere le notifiche più rilevanti e utili.

• Altre Comunicazioni: Qualsiasi forma di comunicazione dal backend, come messaggi SMS, avvisi di sistema o aggiornamenti dell'interfaccia utente, beneficia dell'essere nella lingua dell'utente, garantendo chiarezza e migliorando l'esperienza utente complessiva.

Internazionalizzando il backend, la tua applicazione non solo rispetta le differenze culturali, ma si allinea meglio con le esigenze del mercato globale, rendendolo un passo chiave per scalare i tuoi servizi a livello mondiale.

Iniziare

Installazione

Per iniziare a utilizzare express-intlayer, installa il pacchetto utilizzando npm:

npm install intlayer express-intlayer

Configurazione

Configura le impostazioni di internazionalizzazione creando un file intlayer.config.ts nella radice del tuo progetto:

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

Dichiarare il tuo Contenuto

Crea e gestisci le tue dichiarazioni di contenuto per memorizzare le traduzioni:

import { t, type Dictionary } from "intlayer";const indexContent = {  key: "index",  content: {    exampleOfContent: t({      en: "Example of returned content in English",      fr: "Exemple de contenu renvoyé en français",      "es-ES": "Ejemplo de contenido devuelto en español (España)",      "es-MX": "Ejemplo de contenido devuelto en español (México)",    }),  },} satisfies Dictionary;export default indexContent;

Le dichiarazioni di contenuto possono essere definite ovunque nella tua applicazione purché siano incluse nella directory contentDir (di default, ./src). E corrispondano all'estensione del file di dichiarazione del contenuto (di default, .content.{json,ts,tsx,js,jsx,mjs,mjx,cjs,cjx}).

Per maggiori dettagli, consulta la documentazione sulle dichiarazioni di contenuto.

Configurazione dell'applicazione Express

Configura la tua applicazione Express per utilizzare express-intlayer:

import express, { type Express } from "express";import { intlayer, t, getDictionary, getIntlayer } from "express-intlayer";import dictionaryExample from "./index.content";const app: Express = express();// Carica il gestore delle richieste di internazionalizzazioneapp.use(intlayer());// Rotteapp.get("/t_example", (_req, res) => {  res.send(    t({      en: "Example of returned content in English",      fr: "Exemple de contenu renvoyé en français",      "es-ES": "Ejemplo de contenido devuelto en español (España)",      "es-MX": "Ejemplo de contenido devuelto en español (México)",    })  );});app.get("/getIntlayer_example", (_req, res) => {  res.send(getIntlayer("index").exampleOfContent);});app.get("/getDictionary_example", (_req, res) => {  res.send(getDictionary(dictionaryExample).exampleOfContent);});// Avvia il serverapp.listen(3000, () => console.log(`Listening on port 3000`));

Compatibilità

express-intlayer è completamente compatibile con:

• react-intlayer per applicazioni React
• next-intlayer per applicazioni Next.js
• vite-intlayer per applicazioni Vite Funziona inoltre perfettamente con qualsiasi soluzione di internazionalizzazione in diversi ambienti, inclusi browser e richieste API. Puoi personalizzare il middleware per rilevare la locale tramite header o cookie:

import { Locales, type IntlayerConfig } from "intlayer";const config: IntlayerConfig = {  // ... Altre opzioni di configurazione  middleware: {    headerName: "my-locale-header",    cookieName: "my-locale-cookie",  },};export default config;

Per impostazione predefinita, express-intlayer interpreta l'intestazione Accept-Language per determinare la lingua preferita dal client.

Per maggiori informazioni sulla configurazione e argomenti avanzati, visita la nostra documentazione.

Configurare TypeScript

express-intlayer sfrutta le potenti capacità di TypeScript per migliorare il processo di internazionalizzazione. Il typing statico di TypeScript garantisce che ogni chiave di traduzione sia considerata, riducendo il rischio di traduzioni mancanti e migliorando la manutenibilità.

Assicurati che i tipi autogenerati (di default in ./types/intlayer.d.ts) siano inclusi nel tuo file tsconfig.json.

{  // ... Le tue configurazioni TypeScript esistenti  "include": [    // ... Le tue configurazioni TypeScript esistenti    ".intlayer/**/*.ts", // Includi i tipi autogenerati  ],}

Estensione VS Code

Per migliorare la tua esperienza di sviluppo con Intlayer, puoi installare la Estensione ufficiale Intlayer per VS Code.

Installa dal Marketplace di VS Code

Questa estensione offre:

• Completamento automatico per le chiavi di traduzione.
• Rilevamento in tempo reale degli errori per traduzioni mancanti.
• Anteprime inline del contenuto tradotto.
• Azioni rapide per creare e aggiornare facilmente le traduzioni.

Per maggiori dettagli su come utilizzare l'estensione, consulta la documentazione dell'Estensione Intlayer per VS Code.

Configurazione Git

Si consiglia di ignorare i file generati da Intlayer. Questo ti permette di evitare di committarli nel tuo repository Git.

Per fare ciò, puoi aggiungere le seguenti istruzioni al tuo file .gitignore:

# Ignora i file generati da Intlayer.intlayer

Cronologia del Documento

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