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 dell'utente.

    Panoramica

    La funzione t viene utilizzata per definire e recuperare traduzioni per un determinato set di lingue. 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, passa senza problemi alla lingua predefinita specificata nella configurazione.

    Caratteristiche principali

    • Localizzazione dinamica: seleziona automaticamente la traduzione più appropriata per il client.
    • Fallback alla lingua predefinita: passa a una lingua predefinita se la lingua preferita del client non è disponibile, garantendo continuità nell'esperienza utente.
    • Leggero e veloce: progettato per applicazioni ad alte prestazioni, garantendo un sovraccarico minimo.
    • Supporto alla modalità rigorosa: applica un'aderenza rigorosa alle lingue dichiarate per un comportamento affidabile.

    Firma della funzione

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

    Parametri

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

    Restituisce

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

    Caricamento del gestore delle richieste di 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 garantisce una corretta gestione del rilevamento della lingua 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:

    src/index.ts
    import express, { type Express } from "express";import { intlayer } from "express-intlayer";const app: Express = express();// Carica il gestore delle richieste di internazionalizzazioneapp.use(intlayer());// Definisci le tue route dopo aver caricato il middlewareapp.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 dell'utente in base a intestazioni, 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'utilizzo della funzione t genererà errori di runtime poiché le informazioni sulla lingua non saranno disponibili.

    Esempi di utilizzo

    Esempio base

    Servire contenuti localizzati in diverse lingue:

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

    Richieste del 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! (lingua predefinita).

    Gestione degli errori

    Fornire messaggi di errore in più lingue:

    src/index.ts
    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.",    })  );});

    Utilizzo di varianti di lingua

    Specificare traduzioni per varianti specifiche di lingua:

    src/index.ts
    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 una lingua preferita non è disponibile, la funzione t passerà alla lingua predefinita definita nella configurazione:

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

    Ad 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 passerà al valore di Locales.ENGLISH.

    Applicazione della modalità rigorosa

    Configura la funzione t per applicare un'aderenza rigorosa alle lingue dichiarate:

    Modalità Comportamento
    strict Tutte le lingue dichiarate devono avere traduzioni fornite. Le lingue mancanti generano errori.
    inclusive Le lingue dichiarate devono avere traduzioni. Le lingue mancanti generano avvisi ma sono accettate.
    loose Qualsiasi lingua esistente è accettata, anche se non dichiarata.

    Esempio di configurazione:

    intlayer.config.ts
    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 è sicura per i tipi quando utilizzata con TypeScript. Definisci un oggetto di traduzioni sicuro per i tipi:

    src/index.ts
    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

    Problema Causa Soluzione
    Funzione t non funzionante Middleware non caricato Assicurati che app.use(intlayer()) sia aggiunto prima delle route.
    Errore di traduzioni mancanti Modalità rigorosa abilitata senza tutte le lingue Fornisci tutte le traduzioni richieste.

    Suggerimenti per un utilizzo efficace

    1. Centralizza le traduzioni: utilizza un modulo centralizzato o file JSON per gestire le traduzioni e migliorare la manutenibilità.
    2. Valida le traduzioni: assicurati che ogni variante di lingua abbia una traduzione corrispondente per evitare fallback non necessari.
    3. Combina con i18n frontend: sincronizza con l'internazionalizzazione frontend per un'esperienza utente senza interruzioni in tutta l'app.
    4. Valuta le prestazioni: testa i tempi di risposta dell'app quando aggiungi traduzioni per garantire un impatto minimo.

    Conclusione

    La funzione t è uno strumento potente per l'internazionalizzazione backend. Utilizzandola efficacemente, puoi creare un'applicazione più inclusiva e user-friendly per un pubblico globale. Per un utilizzo avanzato e opzioni di configurazione dettagliate, consulta la documentazione.

    Se hai un’idea per migliorare questa documentazione, non esitare a contribuire inviando una pull request su GitHub.

    Collegamento GitHub alla documentazione
    express-intlayerreact-intlayer