Ricevi notifiche sui prossimi lanci di Intlayer
    Creazione:2024-12-02Ultimo aggiornamento:2025-06-29

    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

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

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

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

    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.",    })  );});

    Uso delle Varianti di Locale

    Specifica traduzioni per varianti specifiche di locale:

    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 un locale preferito non è disponibile, la funzione t utilizzerà come fallback il locale predefinito definito 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;

    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:

    Modalità Comportamento
    strict Tutte le localizzazioni dichiarate devono avere traduzioni fornite. Le localizzazioni mancanti genereranno errori.
    inclusive Le localizzazioni dichiarate devono avere traduzioni. Le localizzazioni mancanti generano avvisi ma sono accettate.
    loose Qualsiasi localizzazione 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 è type-safe quando usata con TypeScript. Definisci un oggetto di traduzioni type-safe:

    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 funziona Middleware non caricato Assicurarsi che app.use(intlayer()) sia aggiunto prima delle rotte.
    Errore di traduzioni mancanti Modalità strict attivata senza tutte le localizzazioni Fornire tutte le traduzioni richieste.

    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.

    Cronologia del Documento

    • 5.5.10 - 2025-06-29: Inizio cronologia
    Ricevi notifiche sui prossimi lanci di Intlayer