Traduci il tuo sito backend Elysia utilizzando Intlayer | Internazionalizzazione (i18n)

elysia-intlayer è un potente plugin di internazionalizzazione (i18n) per applicazioni Elysia, progettato per rendere i tuoi servizi backend accessibili a livello globale fornendo risposte localizzate in base alle preferenze del client.

Vedi l'implementazione del package su GitHub: https://github.com/aymericzip/intlayer/tree/main/packages/elysia-intlayer

Casi d'uso pratici

• Visualizzazione degli errori del backend nella lingua dell'utente: Quando si verifica un errore, visualizzare i messaggi nella lingua nativa dell'utente migliora la comprensione e riduce la frustrazione. Questo è particolarmente utile per i messaggi di errore dinamici che potrebbero essere mostrati in componenti front-end come toast o modal.
• Recupero di contenuti multilingue: Per le applicazioni che recuperano contenuti da un database, l'internazionalizzazione garantisce che tu possa servire questo contenuto in più lingue. Questo è cruciale per piattaforme come siti di e-commerce o sistemi di gestione dei contenuti che hanno bisogno di visualizzare 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, l'invio di email nella lingua del destinatario può aumentare significativamente l'engagement e l'efficacia.
• Notifiche push multilingue: Per le applicazioni mobili, l'invio di notifiche push nella lingua preferita dall'utente può migliorare l'interazione e la retention. Questo tocco personale può rendere le notifiche più rilevanti e azionabili.
• Altre comunicazioni: Qualsiasi forma di comunicazione dal backend, come messaggi SMS, avvisi di sistema o aggiornamenti dell'interfaccia utente, beneficia di 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 anche meglio alle esigenze del mercato globale, rendendola un passo fondamentale nel ridimensionamento dei tuoi servizi a livello mondiale.

Iniziare

Consulta il Template dell'Applicazione su GitHub.

Installazione

Per iniziare a utilizzare elysia-intlayer, installa il pacchetto usando npm:

npx intlayer init --interactive

il flag --interactive è opzionale. Usa intlayer-cli init se sei un agente AI.

Questo comando rileverà il tuo ambiente e installerà i pacchetti necessari. Per esempio:

npm install intlayer elysia-intlayer

Elysia è pensato per il runtime Bun. elysia-intlayer si affida ad AsyncLocalStorage (invece della libreria cls-hooked usata dai plugin Intlayer basati su Node) proprio perché Bun non implementa async_hooks.createHook.

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],
    /**
     * Locale predefinita usata come fallback se la locale richiesta non viene trovata.
     */
    defaultLocale: Locales.ENGLISH,
  },
};

export default config;

Dichiara il Tuo Contenuto

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

import { t, type Dictionary } from "intlayer";

const indexContent = {
  key: "index",
  content: {
    exampleOfContent: t({
      it: "Esempio di contenuto restituito in italiano",
      en: "Example of returned content in English",
      fr: "Exemple de contenu renvoyé en français",
      es: "Ejemplo de contenido devuelto en español",
    }),
  },
} satisfies Dictionary;

export default indexContent;

Le tue dichiarazioni di contenuto possono essere definite ovunque nella tua applicazione purché siano incluse nella directory contentDir (per impostazione predefinita, ./src). E corrispondano all'estensione del file di dichiarazione del contenuto (per impostazione predefinita, .content.{json,ts,tsx,js,jsx,mjs,cjs,md,mdx,yaml,yml}).

Per ulteriori dettagli, consulta la documentazione sulla dichiarazione del contenuto.

Configurazione dell'Applicazione Elysia

Configura la tua applicazione Elysia per utilizzare elysia-intlayer:

import { Elysia } from "elysia";
import { intlayer } from "elysia-intlayer";

const app = new Elysia()
  // Carica il plugin di internazionalizzazione
  .use(intlayer())
  // Route
  .get("/", ({ intlayer }) => ({
    // Locale utilizzato per questa richiesta, negoziato da `Accept-Language` o letto dall'archiviazione
    locale: intlayer!.locale,
    greeting: intlayer!.t({
      it: "Ciao",
      en: "Hello",
      fr: "Bonjour",
      es: "Hola",
    }),
    content: intlayer!.getIntlayer("index").exampleOfContent,
  }))
  .listen(3000);

console.log(
  `🦊 Elysia is running at ${app.server?.hostname}:${app.server?.port}`
);

Il plugin registra il proprio contesto tramite un derive globale, che Elysia tipizza come Partial<{ intlayer: IntlayerContext }>. A runtime il valore è sempre presente per le route registrate dopo .use(intlayer()), quindi usa la non-null assertion (intlayer!.locale) — oppure l'optional chaining — per soddisfare TypeScript in modalità strict.

Il contesto della route espone:

Gli stessi helper sono esportati anche in versione standalone. Risolvono la richiesta corrente tramite AsyncLocalStorage, quindi puoi richiamarli senza destrutturare il contesto:

import { Elysia } from "elysia";
import { intlayer, t, getDictionary, getIntlayer } from "elysia-intlayer";
import dictionaryExample from "./index.content";

const app = new Elysia()
  .use(intlayer())
  .get("/t_example", () =>
    t({
      it: "Esempio di contenuto restituito in italiano",
      en: "Example of returned content in English",
      fr: "Exemple de contenu renvoyé en français",
      es: "Ejemplo de contenido devuelto en español",
    })
  )
  .get("/getIntlayer_example", () => getIntlayer("index").exampleOfContent)
  .get(
    "/getDictionary_example",
    () => getDictionary(dictionaryExample).exampleOfContent
  )
  .listen(3000);

Il contesto della richiesta viene rilasciato una volta mappata la risposta, così gli helper autonomi non si risolvono mai su una richiesta già terminata. Quando vengono chiamati al di fuori di una richiesta gestita dal plugin, ricadono sulla locale predefinita configurata.

Esegui la tua applicazione

Aggiungi gli script di Intlayer al tuo package.json. intlayer build compila le tue dichiarazioni di contenuto nella directory .intlayer e genera i tipi TypeScript:

{
  "scripts": {
    "dev": "intlayer build && bun run --watch src/index.ts",
    "build": "intlayer build",
    "start": "bun run src/index.ts",
    "i18n:fill": "intlayer fill",
    "i18n:test": "intlayer test"
  }
}

Poi avvia il server:

bun run dev

Testa la negoziazione della locale con Accept-Language:

curl -H "Accept-Language: fr" http://localhost:3000/
# {"locale":"fr","greeting":"Bonjour","content":"Exemple de contenu renvoyé en français"}

curl -H "Accept-Language: es" http://localhost:3000/
# {"locale":"es","greeting":"Hola","content":"Ejemplo de contenido devuelto en español"}

intlayer build non è strettamente necessario prima di bun run src/index.ts: il plugin prepara i dizionari anche all'avvio dell'applicazione Elysia. Eseguirlo in anticipo mantiene i tipi generati allineati per il tuo editor ed evita il costo della build alla prima richiesta.

Compatibilità

elysia-intlayer è completamente compatibile con:

• react-intlayer per applicazioni React
• next-intlayer per applicazioni Next.js
• vite-intlayer per applicazioni Vite

Funziona inoltre in modo fluido con qualsiasi soluzione di internazionalizzazione in vari ambienti, inclusi browser e richieste API.

Per impostazione predefinita, il plugin risolve la locale in questo ordine:

1. Il cookie INTLAYER_LOCALE.
2. L'header x-intlayer-locale.
3. La negoziazione dell'header Accept-Language.

Puoi personalizzare il cookie e l’header usati per il rilevamento della locale:

import { Locales, type IntlayerConfig } from "intlayer";

const config: IntlayerConfig = {
  // ... Altre opzioni di configurazione
  routing: {
    storage: [
      { type: "header", name: "my-locale-header" },
      { type: "cookie", name: "my-locale-cookie" },
    ],
  },
};

export default config;

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

Configura TypeScript

elysia-intlayer sfrutta le solide capacità di TypeScript per migliorare il processo di internazionalizzazione. La tipizzazione statica di TypeScript garantisce che ogni chiave di traduzione sia contabilizzata, riducendo il rischio di traduzioni mancanti e migliorando la manutenibilità.

Assicurati che i tipi generati automaticamente (per impostazione predefinita 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 generati automaticamente
  ],
}

Estensione VS Code

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

Installa dal VS Code Marketplace

Questa estensione fornisce:

• Autocompletamento per le chiavi di traduzione.
• Rilevamento errori in tempo reale per traduzioni mancanti.
• Anteprime inline dei contenuti tradotti.
• 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 consente di evitare di eseguirne il commit nel repository Git.

Per farlo, puoi aggiungere le seguenti istruzioni al tuo file .gitignore:

# Ignora i file generati da Intlayer
.intlayer