Documentazione: funzione t in express-intlayer

La funzione t nel pacchetto express-intlayer è l'utilità principale per fornire risposte localizzate nella tua applicazione Express. Semplifica l'internazionalizzazione (i18n) selezionando dinamicamente il contenuto in base alla lingua preferita dall'utente.

Panoramica

La funzione t viene utilizzata per definire e recuperare le traduzioni per un insieme di lingue specificato. Determina automaticamente la lingua appropriata da restituire in base alle impostazioni della richiesta del client, come l'intestazione Accept-Language. Se la lingua preferita non è disponibile, effettua un fallback elegante alla locale predefinita specificata nella tua configurazione.

Caratteristiche principali

• Localizzazione Dinamica: Seleziona automaticamente la traduzione più appropriata per il client.
• Fallback alla locale predefinita: Effettua un fallback a una locale predefinita se la lingua preferita dal client non è disponibile, garantendo continuità nell'esperienza utente.
• Leggero e Veloce: Progettato per applicazioni ad alte prestazioni, assicurando un overhead minimo.
• Supporto alla Modalità Strict: Impone un'aderenza rigorosa alle localizzazioni dichiarate per un comportamento affidabile.

Firma della Funzione

t(translations: Record<string, string>): string;

Parametri

• translations: Un oggetto in cui le chiavi sono codici di localizzazione (es. en, fr, es-MX) e i valori sono le stringhe tradotte corrispondenti.

Ritorna

• Una stringa che rappresenta il contenuto nella lingua preferita dal client.

Caricamento del Gestore di Richieste per l'Internazionalizzazione

Per garantire che la funzionalità di internazionalizzazione fornita da express-intlayer funzioni correttamente, devi caricare il middleware di internazionalizzazione all'inizio della tua applicazione Express. Questo abilita la funzione t e assicura una corretta gestione del rilevamento della locale e della traduzione.

Posiziona il middleware app.use(intlayer()) prima di qualsiasi route nella tua applicazione per garantire che tutte le route beneficino dell'internazionalizzazione:

import express, { type Express } from "express";
import { intlayer } from "express-intlayer";

const app: Express = express();

// Carica il gestore delle richieste di internazionalizzazione
app.use(intlayer());

// Definisci le tue route dopo aver caricato il middleware
app.get("/", (_req, res) => {
  res.send(
    t({
      en: "Hello, World!",
      fr: "Bonjour le monde!",
      es: "¡Hola, Mundo!",
    })
  );
});

Perché è Necessario

• Rilevamento della Lingua: Il middleware intlayer elabora le richieste in arrivo per rilevare la lingua preferita dall'utente basandosi su header, cookie o altri metodi configurati.
• Contesto di Traduzione: Imposta il contesto necessario affinché la funzione t operi correttamente, garantendo che le traduzioni vengano restituite nella lingua corretta.
• Prevenzione degli Errori: Senza questo middleware, l'uso della funzione t genererà errori a runtime perché le informazioni sulla lingua necessarie non saranno disponibili.

Esempi di Utilizzo

Esempio Base

Servi contenuti localizzati in diverse lingue:

app.get("/", (_req, res) => {
  res.send(
    t({
      en: "Welcome!",
      fr: "Bienvenue!",
      es: "¡Bienvenido!",
    })
  );
});

Richieste Client:

• Un client con Accept-Language: fr riceverà Bienvenue!.
• Un client con Accept-Language: es riceverà ¡Bienvenido!.
• Un client con Accept-Language: de riceverà Welcome! (locale predefinito).

Gestione degli Errori

Fornire messaggi di errore in più lingue:

app.get("/error", (_req, res) => {
  res.status(500).send(
    t({
      en: "An unexpected error occurred.",
      fr: "Une erreur inattendue s'est produite.",
      es: "Ocurrió un error inesperado.",
    })
  );
});

Uso delle Varianti di Locale

Specifica traduzioni per varianti specifiche di locale:

app.get("/greet", (_req, res) => {
  res.send(
    t({
      en: "Hello!",
      "en-GB": "Hello, mate!",
      fr: "Bonjour!",
      "es-MX": "¡Hola, amigo!",
      "es-ES": "¡Hola!",
    })
  );
});

app.get("/greet", (_req, res) => {
  res.send(
    t({
      en: "Hello!",
      "en-GB": "Hello, mate!",
      fr: "Bonjour!",
      "es-MX": "¡Hola, amigo!",
      "es-ES": "¡Hola!",
    })
  );
});

app.get("/greet", (_req, res) => {
  res.send(
    t({
      en: "Hello!",
      "en-GB": "Hello, mate!",
      fr: "Bonjour!",
      "es-MX": "¡Hola, amigo!",
      "es-ES": "¡Hola!",
    })
  );
});

Argomenti Avanzati

Meccanismo di Fallback

Se un locale preferito non è disponibile, la funzione t utilizzerà come fallback il locale predefinito definito nella configurazione:

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

const config = {
  internationalization: {
    locales: [Locales.ENGLISH, Locales.FRENCH, Locales.SPANISH],
    defaultLocale: Locales.ENGLISH,
  },
} satisfies IntlayerConfig;

export default config;

Per esempio:

• Se defaultLocale è Locales.CHINESE e un client richiede Locales.DUTCH, la traduzione restituita sarà quella di Locales.CHINESE.
• Se defaultLocale non è definito, la funzione t utilizzerà come fallback il valore di Locales.ENGLISH.

Applicazione della modalità rigorosa

Configura la funzione t per far rispettare rigorosamente le localizzazioni dichiarate:

Esempio di configurazione:

import { type IntlayerConfig } from "intlayer";

const config = {
  // ... La tua configurazione esistente
  internationalization: {
    // ... La tua configurazione di internazionalizzazione esistente
    strictMode: "strict", // Applica la modalità rigorosa
  },
} satisfies IntlayerConfig;

export default config;

Integrazione con TypeScript

La funzione t è type-safe quando usata con TypeScript. Definisci un oggetto di traduzioni type-safe:

import { type LanguageContent } from "express-intlayer";

const translations: LanguageContent<string> = {
  en: "Good morning!",
  fr: "Bonjour!",
  es: "¡Buenos días!",
};

app.get("/morning", (_req, res) => {
  res.send(t(translations));
});

Errori Comuni e Risoluzione dei Problemi

Consigli per un Uso Efficace

1. Centralizza le Traduzioni: Usa un modulo centralizzato o file JSON per gestire le traduzioni e migliorare la manutenibilità.
2. Valida le Traduzioni: Assicurati che ogni variante linguistica abbia una traduzione corrispondente per evitare fallback non necessari.
3. Combina con l'i18n del Frontend: Sincronizza con l'internazionalizzazione del frontend per un'esperienza utente fluida in tutta l'app.
4. Valuta le Prestazioni: Testa i tempi di risposta della tua app quando aggiungi traduzioni per garantire un impatto minimo.

Conclusione

La funzione t è uno strumento potente per l'internazionalizzazione del backend. Usandola efficacemente, puoi creare un'applicazione più inclusiva e facile da usare per un pubblico globale. Per un utilizzo avanzato e opzioni di configurazione dettagliate, consulta la documentazione.