Garantindo Verificação de Chaves em dicionários i18n com TypeScript para React

Introdução

Manter a consistência de tradução em aplicações React que usam bibliotecas como react-i18next é um desafio recorrente. Um problema comum é evitar chamadas a chaves de tradução inexistentes, que podem gerar erros em tempo de execução ou, pior, exibir textos incorretos para o usuário. Para melhorar a experiência de desenvolvimento e evitar esses problemas, a verificação de chaves em tempo de compilação com TypeScript surge como uma solução prática e potente.

Diagnóstico do problema

O cenário típico envolve um dicionário de traduções estruturado como objetos aninhados. Quando usamos a função t para buscar uma tradução, passamos uma string com o caminho até a chave desejada. Se essa chave não existir, o erro só será percebido em tempo de execução, o que pode afetar a qualidade da entrega.

Por exemplo, imagine um dicionário assim:

const dict = {
  footer: {
    copyright: "Direitos reservados",
  },
  header: {
    logo: "Logo da Empresa",
    link: "Link do Header",
  },
}. 

Queremos que o TypeScript nos avise se tentarmos usar uma chave inexistente, como footer.logo, que não existe. Sem uma tipagem adequada, o compilador não consegue detectar esse erro.

Abordagem de solução

A estratégia envolve criar tipos que representam as possíveis chaves de um objeto complexo, permitindo que o TypeScript realize verificações em tempo de compilação.

Passo 1: Obter todas as chaves possíveis

A primeira etapa é gerar um tipo que liste todas as possíveis combinações de chaves, incluindo caminhos aninhados usando template literals:

type DeepKeys<T> = T extends object ? {
  [K in keyof T]-?: `${K & string}` | `${K & string}.${DeepKeys<T[K]>}`
}[keyof T] : "". 

Sem esse critério, a solução pode parecer simples no começo e cara no suporte.

Este tipo recursivamente constrói uma união de todas as chaves possíveis, como 'footer', 'footer.copyright', 'header.logo', etc. O valor aparece melhor quando operação, produto e engenharia olham para o mesmo risco.

Passo 2: Garantir que a chave passada exista

A seguir, podemos definir uma função de tradução genérica que aceita apenas chaves válidas, usando o tipo gerado:

function t<P extends DeepKeys<typeof dict>>(p: P): string {
  // implementação fictícia
  return ''. }

Assim, se tentarmos passar uma chave que não existe, o TypeScript emitirá erro de compilação. Por isso, o recorte precisa considerar manutenção, validação e caminho de volta. Esse contexto ajuda a separar ganho real de novidade difícil de sustentar. A decisão fica mais saudável quando o time consegue medir o impacto depois.

Passo 3: Melhorando a experiência com IntelliSense

Para facilitar o uso, podemos criar um tipo que fornece autocompletar no editor, ajudando a selecionar a chave correta:

type AllKeys = DeepKeys<typeof dict>. // Agora, ao usar t, o editor sugere as chaves válidas Esse contexto ajuda a separar ganho real de novidade difícil de sutsentar. A decisão fica mais saudável quando o time consegue medir o impacto depois. Sem esse critério, a solução pode parecer simples no começo e cara no suporte. O valor aparece melhor quando operação, produto e engenharia olham para o mesmo risco.

// Exemplo de uso:
const texto = t('footer.copyright'). // OK
const erro = t('footer.logo'). // Erro em tempo de compilação

A decisão fica mais saudável quando o time consegue medir o impacto depois. Sem esse critério, a solução pode parecer simples no começo e cara no suporte. O valor aparece melhor quando operação, produto e engenharia olham para o mesmo risco. Por isso, o recorte precisa considerar manutenção, validação e caminho de volta. Esse contexto ajuda a separar ganho real de novidade difícil de sustentar.

Limitações e tradeoffs

Apesar do método ser bastante eficaz, há pontos a considerar:

• Recursão no TypeScript: objetos muito profundos podem alcançar limites de recursão do compilador.
• Manutenção: a geração de tipos dinâmicos pode exigir ajustes quando o dicionário muda drasticamente.
• Complexidade de implementação: construir esses tipos demanda atenção à recursividade e performance do compilador.

Passos finais e recomendações

Para implementar essa estratégia, recomenda-se: 1. Criar tipos genéricos recursivos que extraem todas as possíveis chaves. 2. Usar esses tipos na assinatura da função t para validação de chaves. 3. Manter os dicionários bem estruturados e documentados. 4. Testar a integração com o TypeScript para evitar problemas de performance ou limites de recursão.

Essa abordagem melhora significativamente a confiabilidade do sistema de tradução, além de potencializar a experiência do desenvolvedor com autocompletar e validações em tempo de compilação. A adoção de tipos avançados, como template literals, foi um avanço recente no TypeScript, e usá-los nesse contexto é um exemplo de como aproveitar a evolução da linguagem para resolver problemas práticos. Sem esse critério, a solução pode parecer simples no começo e cara no suporte. O valor aparece melhor quando operação, produto e engenharia olham para o mesmo risco. Por isso, o recorte precisa considerar manutenção, validação e caminho de volta.