Traduci il tuo backend Fastify utilizzando Intlayer | Internazionalizzazione (i18n)

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

Casi d'uso pratici

• Mostrare gli errori del backend nella lingua dell'utente: Quando si verifica un errore, mostrare 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.
• Recuperare contenuti multilingue: Per applicazioni che estraggono contenuti da un database, l'internazionalizzazione garantisce la possibilità di servire tali contenuti in più lingue. Questo è fondamentale 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: Sia che si tratti di email transazionali, campagne di marketing o notifiche, inviare le email nella lingua del destinatario può aumentare significativamente il coinvolgimento e l'efficacia.
• Notifiche push multilingue: Per le applicazioni mobili, inviare notifiche push nella lingua preferita dall'utente può migliorare l'interazione e la retention. Questo tocco personale può rendere le notifiche più rilevanti e facilmente azionabili.
• Altre comunicazioni: Qualsiasi forma di comunicazione dal backend, come SMS, avvisi di sistema o aggiornamenti dell'interfaccia utente, trae vantaggio dall'essere nella lingua dell'utente, garantendo chiarezza e migliorando l'esperienza utente complessiva.

Internationalizzando il backend, la tua applicazione non solo rispetta le differenze culturali ma si allinea anche meglio alle esigenze dei mercati globali, diventando così un passaggio chiave per scalare i tuoi servizi a livello mondiale.

Per iniziare

Installazione

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

npm install intlayer fastify-intlayernpx intlayer init

Configurazione

Configura le impostazioni di internazionalizzazione creando un file intlayer.config.ts nella root 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 contenuto

Crea e gestisci le dichiarazioni di contenuto per memorizzare 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-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 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 dei file di dichiarazione del contenuto (per impostazione predefinita, .content.{json,ts,tsx,js,jsx,mjs,mjx,cjs,cjx}).

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

Impostazione dell'applicazione Fastify

Configura la tua applicazione Fastify per usare fastify-intlayer:

import Fastify from "fastify";import { intlayer, t, getDictionary, getIntlayer } from "fastify-intlayer";import dictionaryExample from "./index.content";const fastify = Fastify({ logger: true });// Carica il plugin di internazionalizzazioneawait fastify.register(intlayer);// Rottefastify.get("/t_example", async (_req, reply) => {  return t({    it: "Esempio di contenuto restituito in italiano",    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)",  });});fastify.get("/getIntlayer_example", async (_req, reply) => {  return getIntlayer("index").exampleOfContent;});fastify.get("/getDictionary_example", async (_req, reply) => {  return getDictionary(dictionaryExample).exampleOfContent;});// Avvia il serverconst start = async () => {  try {    await fastify.listen({ port: 3000 });  } catch (err) {    fastify.log.error(err);    process.exit(1);  }};start();

Compatibilità

fastify-intlayer è completamente compatibile con:

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

Funziona anche 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, fastify-intlayer interpreterà l'intestazione Accept-Language per determinare la lingua preferita del client.

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

Configurare TypeScript

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

Assicurati che i tipi autogenerati (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 auto-generati  ],}

Estensione per VS Code

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

Installa dal VS Code Marketplace

Questa estensione offre:

• Completamento automatico per le chiavi di traduzione.
• Rilevamento degli 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 usare l'estensione, consulta la documentazione dell'Estensione Intlayer per VS Code.

Configurazione Git

È consigliabile ignorare i file generati da Intlayer. Questo ti permette di evitare di commetterli nel tuo repository Git.

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

# Ignora i file generati da Intlayer.intlayer