Receba notificações sobre os próximos lançamentos de Intlayer
    Criação:2024-12-02Última atualização:2025-06-29

    Documentação: Função t no express-intlayer

    A função t no pacote express-intlayer é a utilidade principal para fornecer respostas localizadas na sua aplicação Express. Ela simplifica a internacionalização (i18n) ao selecionar dinamicamente o conteúdo com base na língua preferida do usuário.

    Visão Geral

    A função t é usada para definir e recuperar traduções para um conjunto específico de idiomas. Ela determina automaticamente a língua apropriada a ser retornada com base nas configurações da requisição do cliente, como o cabeçalho Accept-Language. Se a língua preferida não estiver disponível, ela recorre de forma elegante ao locale padrão especificado na sua configuração.

    Principais Características

    • Localização Dinâmica: Seleciona automaticamente a tradução mais apropriada para o cliente.
    • Recurso de Retorno ao Locale Padrão: Retorna a um locale padrão caso a língua preferida do cliente não esteja disponível, garantindo continuidade na experiência do usuário.
    • Leve e Rápido: Projetado para aplicações de alto desempenho, garantindo sobrecarga mínima.
    • Suporte ao Modo Estrito: Impõe aderência rigorosa aos locales declarados para comportamento confiável.

    Assinatura da Função

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

    Parâmetros

    • translations: Um objeto onde as chaves são códigos de locale (ex: en, fr, es-MX) e os valores são as strings traduzidas correspondentes.

    Retorno

    • Uma string representando o conteúdo na língua preferida do cliente.

    Carregando o Manipulador de Requisição de Internacionalização

    Para garantir que a funcionalidade de internacionalização fornecida pelo express-intlayer funcione corretamente, você deve carregar o middleware de internacionalização no início da sua aplicação Express. Isso habilita a função t e assegura o tratamento adequado da detecção de locale e tradução.

    Coloque o middleware app.use(intlayer()) antes de quaisquer rotas na sua aplicação para garantir que todas as rotas se beneficiem da internacionalização:

    src/index.ts
    import express, { type Express } from "express";import { intlayer } from "express-intlayer";const app: Express = express();// Carregar o manipulador de requisição de internacionalizaçãoapp.use(intlayer());// Defina suas rotas após carregar o middlewareapp.get("/", (_req, res) => {  res.send(    t({      en: "Hello, World!",      fr: "Bonjour le monde!",      es: "¡Hola, Mundo!",    })  );});

    Por que isso é necessário

    • Detecção de Localidade: O middleware intlayer processa as requisições recebidas para detectar a localidade preferida do usuário com base nos cabeçalhos, cookies ou outros métodos configurados.
    • Contexto de Tradução: Configura o contexto necessário para que a função t opere corretamente, garantindo que as traduções sejam retornadas no idioma correto.
    • Prevenção de Erros: Sem este middleware, usar a função t resultará em erros de tempo de execução porque as informações necessárias sobre a localidade não estarão disponíveis.

    Exemplos de Uso

    Exemplo Básico

    Sirva conteúdo localizado em diferentes idiomas:

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

    Requisições do Cliente:

    • Um cliente com Accept-Language: fr receberá Bienvenue!.
    • Um cliente com Accept-Language: es receberá ¡Bienvenido!.
    • Um cliente com Accept-Language: de receberá Welcome! (local padrão).

    Tratamento de Erros

    Forneça mensagens de erro em vários idiomas:

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

    Usando Variantes de Localidade

    Especifique traduções para variantes específicas de localidade:

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

    Tópicos Avançados

    Mecanismo de Fallback

    Se uma localidade preferida não estiver disponível, a função t fará fallback para a localidade padrão definida na configuração:

    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;

    Por exemplo:

    • Se defaultLocale for Locales.CHINESE e um cliente solicitar Locales.DUTCH, a tradução retornada será o valor padrão de Locales.CHINESE.
    • Se defaultLocale não estiver definido, a função t usará como fallback o valor de Locales.ENGLISH.

    Aplicação do Modo Estrito

    Configure a função t para impor a aderência estrita às localidades declaradas:

    Modo Comportamento
    strict Todas as localidades declaradas devem ter traduções fornecidas. Localidades ausentes gerarão erros.
    inclusive As localidades declaradas devem ter traduções. Localidades ausentes geram avisos, mas são aceitas.
    loose Qualquer localidade existente é aceita, mesmo que não declarada.

    Exemplo de Configuração:

    intlayer.config.ts
    import { type IntlayerConfig } from "intlayer";const config = {  // ... Sua configuração existente  internationalization: {    // ... Sua configuração existente de internacionalização    strictMode: "strict", // Aplicar modo estrito  },} satisfies IntlayerConfig;export default config;

    Integração com TypeScript

    A função t é segura em termos de tipos quando usada com TypeScript. Defina um objeto de traduções com segurança de tipos:

    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));});

    Erros Comuns e Solução de Problemas

    Problema Causa Solução
    Função t não funcionando Middleware não carregado Certifique-se de que app.use(intlayer()) está adicionado antes das rotas.
    Erro de traduções faltando Modo estrito ativado sem todas as localidades Forneça todas as traduções necessárias.

    Dicas para Uso Eficaz

    1. Centralize as Traduções: Use um módulo centralizado ou arquivos JSON para gerenciar as traduções e melhorar a manutenção.
    2. Valide as Traduções: Garanta que cada variante de idioma tenha uma tradução correspondente para evitar retornos desnecessários.
    3. Combine com i18n no Frontend: Sincronize com a internacionalização do frontend para uma experiência de usuário fluida em todo o aplicativo.
    4. Avalie o Desempenho: Teste os tempos de resposta do seu aplicativo ao adicionar traduções para garantir impacto mínimo.

    Conclusão

    A função t é uma ferramenta poderosa para internacionalização no backend. Ao usá-la de forma eficaz, você pode criar uma aplicação mais inclusiva e amigável para um público global. Para uso avançado e opções detalhadas de configuração, consulte a documentação.

    Histórico do Documento

    • 5.5.10 - 2025-06-29: Histórico inicial
    Por que Intlayer?
    Receba notificações sobre os próximos lançamentos de Intlayer