Boas Práticas de i18n
Um resumo condensado das 25 melhores práticas mais importantes, extraídas de todas as páginas desta seção.
//
Busque em todas as páginas da documentação
Um resumo condensado das 25 melhores práticas mais importantes, extraídas de todas as páginas desta seção.
Externalize toda cópia visível ao usuário: Literais em JSX bloqueiam tradutores, quebram regras de plural e impedem QA de truncamento RTL - use t() desde o primeiro dia.
Uma chave por frase completa: Nunca concatene t("welcome") + name + t("exclaim") - a ordem das palavras difere em árabe, japonês e alemão.
Chaves cientes de contexto: Homógrafos em inglês duplicados (close diálogo vs close conta) precisam de chaves distintas - tradutores não podem adivinhar a partir de "close".
JSON em inglês é a locale de origem: Envie alterações em en no mesmo PR que novas chamadas t() - uploads de TMS e scripts de verificação tratam o inglês como autoritativo.
Resolva a locale ao iniciar antes da navegação: Bloqueie o layout raiz até que o padrão do dispositivo e a substituição do AsyncStorage sejam resolvidos - evite o flash em inglês em dispositivos árabes.
Padrão do dispositivo a partir de expo-localization: Use getLocales()[0].languageTag e percorra a lista de preferências - não guesses de Intl ou en-US codificados.
Substituição pelo usuário vence a locale do dispositivo: Persistência de configurações no AsyncStorage (ou perfil do servidor) vence o idioma do SO no próximo lançamento.
Mapeie tags BCP 47 para locales de app suportadas: es-419 → es, pt-PT → pt - tabelas explícitas vencem truncamento de código de idioma puro.
Cadeias de fallback para inglês: Configure fallbackLng (fr-CA → fr → en) - chaves ausentes nunca devem renderizar em branco em produção.
Formate com Intl na borda da exibição: Armazene datas ISO e números brutos em estado/API; formate com languageTag e currencyCode de expo-localization.
Nunca analise entrada formatada por locale: Usuários digitam decimais com , ou . - analise com separadores conhecidos ou seletores estruturados, não strings de exibição invertidas.
Adote i18next após ~100 chaves: Namespaces, plurais, pacotes de idioma 'lazy' e fluxos de trabalho TMS crescem além de helpers t() feitos à mão.
Divida namespaces por recurso: common, auth, billing - não um único translation.json monolítico que entra em conflito em cada merge.
Carregue 'lazy' idiomas não padrão: import() dinâmico por locale mantém o início pequeno - pré-carregue no Wi‑Fi após o usuário selecionar um idioma.
escapeValue: false em react-i18next: React Native Text já escapa - escapeValue: true corrompe apóstrofos e marcação ICU.
Chaves de plural em JSON, não em branches JSX: Use count com sufixos _one / _other - árabe e polonês precisam de mais de duas formas.
Mappers de erro retornam chaves de mensagem: Não strings literais em inglês - resolva com t() em componentes para que cópias offline e de autenticação sejam traduzidas.
RTL é layout, não apenas tradução: Habilite I18nManager, use marginStart/paddingEnd, espelhe ícones direcionais - recarregue ao cruzar LTR ↔ RTL.
Não espelhe logos, mídia ou mapas: Chevrons e setas de voltar viram; marcas e botões de play não.
Atualize locale no Android ao vir para primeiro plano: AppState + getLocales() ao retornar ao ativo - usuários mudam o idioma nas Configurações sem reiniciar.
Pseudolocale antes de long locales serem enviados: en-XA ou strings preenchidas expõem truncamento em botões e abas antes que a cópia alemã chegue.
CI de Tradução em cada PR: i18next-parser extrai + verify-locales paridade - bloqueie merge quando en divergir ou locales necessárias perderem chaves.
TMS para escritas não inglesas: Crowdin/Lokalise baixam para git - tradutores não editam es.json em pull requests manualmente.
testID para E2E, não para asserções de cópia: Detox e Maestro sobrevivem a mudanças de locale quando seletores se desvinculam de rótulos traduzidos.
Flavors de marca podem escopar locales e RTL: Clientes white-label enviam listas de idiomas e regras de direção diferentes sem duplicar código - coordene com a tematização do design system.
expo-localization + i18next / react-i18next + substituição AsyncStorage + I18nManager para RTL + i18next-parser e script de verificação em CI. Comece com Fundamentos de i18n, avance para i18next / react-i18next.
Duas locales, menos de ~100 chaves, sem plurais e sem TMS. Substitua antes de plurais, pacotes 'lazy' ou fluxos de trabalho de tradutor - veja Fundamentos de i18n.
A escolha da locale é independente do tema claro/escuro, mas flavors de marca podem fixar locales suportadas, idioma padrão e política RTL por tenant - Tematização & Flavors de Marca.
Metadados da loja são separados do i18n dentro do app. Locales dentro do app vêm de bundles JSON ou atualizações OTA - CI de Tradução controla catálogos de produção.
I18nManager e ícones espelhadosVersões da Stack: Esta página foi escrita para React 19.2.3, React Native 0.86.0 e Expo SDK 57 (
expo~57.0.4).
Revisado por Chris St. John·Última atualização: 16 de jul. de 2026