Traduci il tuo sito backend Nest usando Intlayer | Internazionalizzazione (i18n)

express-intlayer è un potente middleware di internazionalizzazione (i18n) per applicazioni Express, progettato per rendere i tuoi servizi backend accessibili a livello globale fornendo risposte localizzate in base alle preferenze del client. Poiché NestJS è costruito su Express, puoi integrare perfettamente express-intlayer nelle tue applicazioni NestJS per gestire efficacemente contenuti multilingue.

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 visualizzati in componenti front-end come toast o modali.

• Recupero di contenuti multilingue: Per le applicazioni che estraggono contenuti da un database, l'internazionalizzazione garantisce che tu possa servire questo contenuto in più lingue. Questo è fondamentale per piattaforme come siti di e-commerce o sistemi di gestione dei contenuti che devono 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, inviare 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 fidelizzazione. Questo tocco personale può rendere le notifiche più rilevanti e attuabili.

• Altre comunicazioni: Qualsiasi forma di comunicazione dal backend, come messaggi SMS, avvisi di sistema o aggiornamenti dell'interfaccia utente, beneficia dall'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 chiave nel ridimensionamento dei tuoi servizi a livello mondiale.

Iniziare

Creare un nuovo progetto NestJS

npm install -g @nestjs/cli
nest new my-nest-app

Installazione

Per iniziare a usare express-intlayer, installa il pacchetto usando npm:

npx intlayer init --interactive

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

Questo comando rileverà il tuo ambiente e installerà i pacchetti richiesti. Ad esempio:

npm install intlayer express-intlayer

Configurare tsconfig.json

Per utilizzare Intlayer con TypeScript, assicurati che il tuo tsconfig.json sia configurato per supportare i moduli ES. Puoi farlo impostando le opzioni module e moduleResolution su nodenext.

{
  compilerOptions: {
    module: "nodenext",
    moduleResolution: "nodenext",
    // ... altre opzioni
  },
}

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],
    defaultLocale: Locales.ENGLISH,
  },
};

export default config;

Dichiara il tuo contenuto

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

Le tue 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,cjs,md,mdx,yaml,yml}).

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

Configurazione del Middleware Express

Integra il middleware express-intlayer nella tua applicazione NestJS per gestire l'internazionalizzazione:

import { MiddlewareConsumer, Module, NestModule } from "@nestjs/common";
import { AppController } from "./app.controller";
import { AppService } from "./app.service";
import { intlayer } from "express-intlayer";

@Module({
  imports: [],
  controllers: [AppController],
  providers: [AppService],
})
export class AppModule implements NestModule {
  configure(consumer: MiddlewareConsumer) {
    consumer.apply(intlayer()).forRoutes("*"); // Applica a tutte le rotte
  }
}

Usa le Traduzioni nei Tuoi Servizi o Controller

Ora puoi usare la funzione getIntlayer per accedere alle traduzioni nei tuoi servizi o controller:

import { Injectable } from "@nestjs/common";
import { getIntlayer } from "express-intlayer";

@Injectable()
export class AppService {
  getHello(): string {
    return getIntlayer("app").greet;
  }
}

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
  routing: {
    storage: [
      { type: "header", name: "my-locale-header" },
      { type: "cookie", name: "my-locale-cookie" },
    ],
  },
};

export default config;

Per impostazione predefinita, express-intlayer interpreterà l'intestazione Accept-Language per determinare la lingua preferita del 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 generati automaticamente (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 generati automaticamente
  ],
}

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 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 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

Domande frequenti