A versão em inglês de um analisador de Cache-Control recém-lançado exibiu texto em japonês — seu status indicava “新鮮” em vez de “Fresh”. O erro foi rastreado até uma lógica compartilhada que retornava strings em japonês codificadas diretamente, enquanto a página fornecia apenas rótulos em inglês.

O desenvolvedor constrói uma série de ferramentas leves para o navegador, cada uma com uma página em inglês e uma em japonês que reutilizam as mesmas funções de parsing e a lógica central. Apenas a redação visível deveria ser diferente. Quando o analisador de Cache-Control foi lançado, a interface em inglês exibiu os rótulos corretos, mas os valores renderizados vinham da camada de lógica, que ainda continha literais em japonês. Nenhum erro de console apareceu; a página parecia normal, mas a informação apresentada aos usuários de língua inglesa estava errada.

Por que a lógica compartilhada pode trair a tradução

O bug originou-se de uma escolha de design: a função principal que decide o que mostrar retornava strings literais em japonês. A camada da página, responsável pelo texto em inglês ao redor, nunca teve a chance de substituir esses valores. Como a lógica e a UI estavam bem separadas, o problema permaneceu invisível durante os testes — tudo "funcionava" tecnicamente, embora o idioma voltado para o usuário estivesse incorreto.

A desvantagem é que o idioma usado dentro do módulo compartilhado torna-se o padrão para todo front-end que o consome. Se um idioma diferente for necessário, o padrão torna-se um bug oculto.

A correção: chaves, pacotes e uma rede de segurança

O autor reescreveu a arquitetura para separar as responsabilidades:

  • Message packs agora contêm todas as strings legíveis por humanos para cada idioma.
  • Shared logic retorna apenas chaves simbólicas, nunca texto bruto.
  • Pages buscam a palavra apropriada no pacote relevante com base na chave.

Quando uma mensagem deve incluir um número, o novo código utiliza uma pequena função em vez de uma template string. Isso permite que cada idioma decida onde o número deve ficar, acomodando as diferenças na ordem das palavras.

Um passo simples de análise estática também foi adicionado: o processo de build verifica arquivos compartilhados em busca de caracteres japoneses. Se algum aparecer, o desenvolvedor é alertado imediatamente, evitando que textos estrangeiros codificados diretamente voltem a aparecer.

O que a experiência ensinou ao autor

  1. A tradução atua como uma etapa de revisão. Ao escrever as mensagens em inglês, o autor percebeu que alguns equivalentes em japonês eram vagos. Traduzir forçou uma redação mais clara em ambos os idiomas.
  2. Funções compartilhadas que retornam strings fixam um idioma para todos. Se uma função decide o idioma, qualquer consumidor que espere um diferente herda o erro. O bug não é uma falha de UI; é uma falha de lógica.

Recomendações para quem mantém ferramentas multilíngues

  • Retorne chaves, não strings, das funções principais. Deixe a camada de UI lidar com a localização.
  • Ou passe as strings desejadas para a função como parâmetros. Isso mantém a lógica agnóstica em relação ao idioma.
  • Audite módulos compartilhados em busca de texto em idioma nativo codificado diretamente. Uma busca rápida por caracteres não-ASCII pode revelar problemas ocultos.
  • Adicione uma verificação em tempo de build para caracteres estrangeiros no código compartilhado. A detecção precoce é melhor do que a confusão pós-lançamento.

O que observar a seguir

Conclusão: Se o seu projeto compartilha código entre versões de idiomas, certifique-se de que a parte compartilhada nunca decida a redação. Deixe que cada página forneça suas próprias palavras e você evitará o constrangimento de uma página em inglês que, acidentalmente, fala japonês.