Typesafe-i18n: Internacionalização com suporte total de tipos no TypeScript

No desenvolvimento web moderno, a internacionalização (i18n) vai muito além da simples tradução de texto — é um sistema completo de gerenciamento de localização. Typesafe-i18n é uma biblioteca para TypeScript que eleva a internacionalização a um novo patamar, garantindo segurança total de tipos em todas as etapas: desde a escrita das traduções até o uso no código.

Por que usar esta biblioteca? Soluções tradicionais de i18n (como i18next) geralmente trabalham com strings dinâmicas, o que abre margem para erros: digitação incorreta de chaves, argumentos errados ou traduções ausentes. O Typesafe-i18n resolve esse problema de forma radical: se você escrever LL.WELCOME({name: "João"}), o TypeScript verificará se a chave WELCOME existe, se aceita o parâmetro name e qual o tipo desse parâmetro. Erros de localização se tornam erros de compilação, não bugs em tempo de execução.

A biblioteca é ideal para projetos que exigem tipagem rigorosa: aplicações React/Vue/Angular, servidores Node.js e bibliotecas de componentes. Ela suporta pluralização, interpolação, chaves aninhadas, carregamento assíncrono e geração de tipos baseada nos seus arquivos de tradução. Neste artigo, vamos explorar todos os aspectos do uso do Typesafe-i18n: da instalação às técnicas avançadas.

Instalação

A instalação é feita via npm (ou yarn/pnpm):

npm install typesafe-i18n

Para gerar tipos e arquivos de tradução, você precisará de um pacote adicional:

npm install --save-dev typesafe-i18n-cli

Após a instalação, inicialize o projeto:

npx typesafe-i18n --init

Este comando cria a estrutura básica de pastas e arquivos de configuração.

Início rápido: exemplo funcional mínimo

Vamos criar uma aplicação simples que saúda o usuário em diferentes idiomas.

Passo 1: Crie o arquivo de tradução

Crie o arquivo src/i18n/en/index.ts:

import type { Translation } from '../i18n-types'

const en: Translation = {
   HI: 'Hello {name}!',
   GOODBYE: 'Goodbye, {name}!'
}

export default en

Passo 2: Crie o arquivo de tradução para português

Crie o arquivo src/i18n/pt/index.ts:

import type { Translation } from '../i18n-types'

const pt: Translation = {
   HI: 'Olá, {name}!',
   GOODBYE: 'Tchau, {name}!'
}

export default pt

Passo 3: Execute a geração de tipos

npx typesafe-i18n

Passo 4: Use no código

import { i18n } from './i18n/i18n-util'
import { loadLocale } from './i18n/i18n-util.sync'
import { L } from './i18n/i18n-util'

// Carregando as localizações
loadLocale('en')
loadLocale('pt')

// Criando instância para inglês
const LL_en = i18n('en')
console.log(LL_en.HI({ name: 'Alex' })) // Saída: Hello Alex!

// Alternando para português
const LL_pt = i18n('pt')
console.log(LL_pt.HI({ name: 'João' })) // Saída: Olá, João!

Observe: se você tentar chamar LL_en.HI() sem o argumento name, o TypeScript emitirá um erro de compilação. Se você digitar a chave incorretamente (LL_en.Hello) — também terá um erro.

Métodos e funções principais

Vamos explorar 8 funções e métodos essenciais da biblioteca Typesafe-i18n.

1. i18n(locale: Locales): TranslationFunctions

Assinatura: i18n(locale: Locales): TranslationFunctions

O que faz: Cria uma instância do tradutor para a localidade especificada. Retorna um objeto com todas as funções de tradução.

  
Também na biblioteca
  

                
                  
                 Agendador de Tarefas Swift para iOS/macOS: EventKit e DispatchSource
      
                
                  
                 Geração Swagger/OpenAPI para Node.js (JavaScript): ferramentas e exemplos
      
                
                  
                 Pistache para C++: guia completo com exemplos práticos
      
                
                  
                 PhotosUI para Swift: guia completo com exemplos práticos
      
                
                  
                 Validação de dados em C# (.NET) com FluentValidation: guia completo