Pose una domanda e ottieni un riassunto del documento facendo riferimento a questa pagina e al provider AI di tua scelta
Integrando il server MCP Intlayer al tuo assistente AI, puoi recuperare tutti i documenti direttamente da ChatGPT, DeepSeek, Cursor, VSCode, ecc.
Vedi la documentazione del server MCPIl contenuto di questa pagina è stato tradotto con un'IA.
Vedi l'ultima versione del contenuto originale in ingleseSe hai un’idea per migliorare questa documentazione, non esitare a contribuire inviando una pull request su GitHub.
Collegamento GitHub alla documentazioneCopia il Markdown del documento nella porta-documenti
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
Copiare il codice nella clipboard
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:
Copiare il codice nella clipboard
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:
Copiare il codice nella clipboard
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:
Copiare il codice nella clipboard
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:
Copiare il codice nella clipboard
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:
Copiare il codice nella clipboard
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:
Copiare il codice nella clipboard
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:
Copiare il codice nella clipboard
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
- Centralizza le Traduzioni: Usa un modulo centralizzato o file JSON per gestire le traduzioni e migliorare la manutenibilità.
- Valida le Traduzioni: Assicurati che ogni variante linguistica abbia una traduzione corrispondente per evitare fallback non necessari.
- Combina con l'i18n del Frontend: Sincronizza con l'internazionalizzazione del frontend per un'esperienza utente fluida in tutta l'app.
- 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