Internacionalização de aplicações TypeScript: guia completo com exemplos

Como Parar de Temer e Começar a Localizar: Internacionalização de Aplicações TypeScript

Você já se perguntou por que alguns projetos alcançam um nível internacional enquanto outros permanecem como "startups de língua russa"? Na maioria das vezes, a resposta é simples: localização. Sim, aquela abreviação assustadora i18n que causa um tique nervoso em muitos desenvolvedores. Mas sejamos honestos: tornar uma aplicação TypeScript internacionalizada não é nenhuma ciência de foguetes. É apenas um conjunto de abordagens e ferramentas corretas. Hoje vamos detalhar isso na prática, com exemplos de código reais, sem enrolação e sem teorias abstrusas.

Por que o TypeScript é um Candidato Ideal para i18n?

O TypeScript nos dá o que o JavaScript puro não tem: tipagem estática. Quando se trata de traduções, isso se torna um superpoder. Imagine: você altera uma chave de tradução e o TypeScript grita antes mesmo da aplicação executar: "Ei, você esqueceu de atualizar a tradução no locale espanhol!". Concordo, isso é melhor do que pegar bugs em produção.

Além disso, bibliotecas modernas para i18n em TypeScript permitem gerar tipos diretamente dos arquivos de tradução. Isso significa que o autocomplete na IDE funcionará como um relógio. Sem strings mágicas, sem erros de digitação. Apenas código limpo e seguro.

Escolhendo uma Biblioteca: i18next vs react-intl

Existem dois principais players no mercado: i18next e react-intl (parte do FormatJS). Ambos funcionam muito bem com TypeScript, mas suas abordagens são diferentes.

• i18next — o canivete suíço da internacionalização. Suporta pluralização, interpolação, contextos, carregamento preguiçoso. Ótimo para projetos grandes.
• react-intl — mais leve, adaptado para React. Usa uma abordagem baseada em componentes (<FormattedMessage>) e um poderoso sistema ICU MessageFormat.

Neste artigo, usaremos o i18next com o adaptador oficial para React react-i18next. Por quê? Porque é a stack mais popular e oferece o máximo de controle.

Configuração Passo a Passo: Do Zero à Primeira Tradução

Vamos direto ao ponto. Instale as dependências:

npm install i18next react-i18next i18next-browser-languagedetector

Agora vamos criar um arquivo de configuração. Este é o coração da internacionalização da nossa aplicação TypeScript.

// i18n.tsimport i18n from 'i18next';import { initReactI18next } from 'react-i18next';import LanguageDetector from 'i18next-browser-languagedetector';

import enTranslation from './locales/en/translation.json';import ruTranslation from './locales/ru/translation.json';

i18n  .use(LanguageDetector) // detecção automática do idioma do navegador  .use(initReactI18next) // integração com React  .init({    resources: {      en: { translation: enTranslation },      ru: { translation: ruTranslation },    },    fallbackLng: 'en', // se a tradução não for encontrada    interpolation: {      escapeValue: false, // o React já faz o escape    },  });

export default i18n;

Observe o fallbackLng. Isso é criticamente importante para a experiência do usuário: se um usuário acessar com o navegador configurado para swahili, mostraremos a versão em inglês, e não uma tela em branco.

Estrutura do Arquivo de Tradução

Vamos criar uma pasta locales e, dentro dela, subpastas para cada idioma. Aqui está um exemplo do arquivo en/translation.json:

{  "welcome": "Welcome to our application!",  "description": "This is a {{framework}} app with i18n support.",  "items": {    "zero": "No items",    "one": "One item",    "other": "{{count}} items"  }}

E aqui está sua contraparte em russo:

{  "welcome": "Добро пожаловать в наше приложение!",  "description": "Это приложение на {{framework}} с поддержкой i18n.",  "items": {    "zero": "Нет элементов",