Intlayer

--- createdAt: 2025-11-24 updatedAt: 2025-11-24 title: Compilador vs. i18n Declarativo description: Explorando as compensações arquitetônicas entre a internacionalização "mágica" baseada em compilador e o gerenciamento explícito e declarativo de conteúdo. keywords: - Intlayer - Internacionalização - Blog - Next.js - JavaScript - React - i18n - Compilador - Declarativo slugs: - blog - compiler-vs-declarative-i18n --- # O Caso a Favor e Contra a i18n Baseada em Compilador Se você tem construído aplicações web por mais de uma década, sabe que a Internacionalização (i18n) sempre foi um ponto de atrito. Frequentemente, é a tarefa que ninguém quer fazer — extrair strings, gerenciar arquivos JSON e se preocupar com regras de pluralização. Recentemente, uma nova onda de ferramentas de i18n **"baseadas em compilador"** surgiu, prometendo fazer essa dor desaparecer. A proposta é sedutora: **Basta escrever o texto nos seus componentes e deixar a ferramenta de build cuidar do resto.** Sem chaves, sem imports, apenas mágica. Mas, como em todas as abstrações na engenharia de software, mágica tem um preço. Neste post do blog, exploraremos a transição de bibliotecas declarativas para abordagens baseadas em compilador, as dívidas arquiteturais ocultas que elas introduzem e por que o jeito "chato" ainda pode ser o melhor para aplicações profissionais. ## Índice <TOC/> ## Uma Breve História da Internacionalização Para entender onde estamos, precisamos olhar para onde começamos. Por volta de 2011–2012, o cenário do JavaScript era muito diferente. Bundlers como os conhecemos hoje (Webpack, Vite) não existiam ou estavam em sua infância. Estávamos juntando scripts diretamente no navegador. Nessa época, bibliotecas como **i18next** nasceram. Elas resolveram o problema da única forma possível na época: **Dicionários em tempo de execução**. Você carregava um enorme objeto JSON na memória, e uma função buscava as chaves dinamicamente. Era confiável, explícito e funcionava em qualquer lugar. Avançando para hoje. Temos compiladores poderosos (SWC, bundlers baseados em Rust) que conseguem analisar Árvores de Sintaxe Abstrata (AST) em milissegundos. Esse poder deu origem a uma nova ideia: _Por que estamos gerenciando chaves manualmente? Por que o compilador não pode simplesmente ver o texto "Hello World" e substituí-lo para nós?_ Assim, nasceu o i18n baseado em compilador. > **Exemplo de i18n baseado em compilador:** > > - Paraglide (Módulos tree-shaken que compilam cada mensagem em uma pequena função ESM para que os bundlers possam eliminar automaticamente locais e chaves não utilizados. Você importa mensagens como funções em vez de fazer buscas por chaves de string.) > - LinguiJS (Compilador de macro para função que reescreve macros de mensagem como `<Trans>` em chamadas de função JS simples durante o build. Você obtém a sintaxe ICU/MessageFormat com uma pegada de runtime muito pequena.) > - Lingo.dev (Foca em automatizar o pipeline de localização injetando conteúdo traduzido diretamente durante a construção da sua aplicação React. Pode gerar traduções automaticamente usando IA e integrar-se diretamente ao CI/CD.) > - Wuchale (Pré-processador focado em Svelte que extrai texto inline em arquivos .svelte e compila em funções de tradução sem wrappers. Evita chaves de string e separa completamente a lógica de extração de conteúdo do runtime principal da aplicação.) > - Intlayer (Compilador / CLI de extração que analisa seus componentes, gera dicionários tipados e pode opcionalmente reescrever o código para usar conteúdo explícito do Intlayer. O objetivo é usar o compilador para velocidade mantendo um núcleo declarativo e agnóstico ao framework.) > **Exemplo de i18n declarativo:** > > - i18next / react-i18next / next-i18next (O padrão maduro da indústria que usa dicionários JSON em runtime e um extenso ecossistema de plugins) > - react-intl (Parte da biblioteca FormatJS, focada na sintaxe padrão de mensagens ICU e formatação rigorosa de dados) > - next-intl (Otimizado especificamente para Next.js com integração para o App Router e React Server Components) > - vue-i18n / @nuxt/i18n (A solução padrão do ecossistema Vue que oferece blocos de tradução a nível de componente e integração estreita com reatividade) > - svelte-i18n (Um wrapper leve em torno dos stores do Svelte para traduções reativas em tempo de execução) > - angular-translate (A biblioteca legada de tradução dinâmica que depende de buscas por chaves em tempo de execução ao invés de mesclagem em tempo de build) > - angular-i18n (A abordagem nativa do Angular, ahead-of-time, que mescla arquivos XLIFF diretamente nos templates durante a build) > - Tolgee (Combina código declarativo com um SDK em contexto para edição "click-to-translate" diretamente na interface) > - Intlayer (Abordagem por componente, usando arquivos de declarações de conteúdo que permitem tree-shaking nativo e validação TypeScript) ## O Compilador Intlayer Embora o **Intlayer** seja uma solução que fundamentalmente incentiva uma **abordagem declarativa** para o seu conteúdo, ele inclui um compilador para ajudar a acelerar o desenvolvimento ou facilitar prototipagem rápida. O compilador Intlayer percorre a AST (Abstract Syntax Tree) dos seus componentes React, Vue ou Svelte, assim como outros arquivos JavaScript/TypeScript. Seu papel é detectar strings hardcoded e extraí-las para declarações dedicadas `.content`. > Para mais detalhes, consulte a documentação: [Documentação do Compilador Intlayer](https://github.com/aymericzip/intlayer/blob/main/docs/docs/pt/compiler.md) ## O Encanto do Compilador (A Abordagem "Mágica") Há uma razão pela qual essa nova abordagem está em alta. Para um desenvolvedor, a experiência é incrível. ### 1. Velocidade e "Flow" Quando você está concentrado, parar para pensar em um nome de variável semântico (`home_hero_title_v2`) quebra seu fluxo. Com a abordagem do compilador, você digita `<p>Welcome back</p>` e continua. O atrito é zero. ### 2. A Missão de Resgate do Legado Imagine herdar uma base de código enorme com 5.000 componentes e nenhuma tradução. Adaptar isso com um sistema manual baseado em chaves é um pesadelo que dura meses. Uma ferramenta baseada em compilador atua como uma estratégia de resgate, extraindo instantaneamente milhares de strings sem que você precise tocar em um único arquivo manualmente. ### 3. A Era da IA Este é um benefício moderno que não devemos ignorar. Assistentes de codificação com IA (como Copilot ou ChatGPT) geram naturalmente JSX/HTML padrão. Eles não conhecem seu esquema específico de chaves de tradução. - **Declarativo:** Você precisa reescrever a saída da IA para substituir o texto por chaves. - **Compilador:** Você copia e cola o código da IA, e ele simplesmente funciona. ## A Realidade: Por que a "Magia" é Perigosa Embora a "mágica" seja atraente, a abstração apresenta vazamentos. Confiar em uma ferramenta de build para entender a intenção humana introduz fragilidade arquitetural. ### Fragilidade Heurística (O Jogo de Adivinhação) O compilador precisa adivinhar o que é conteúdo e o que é código. Isso leva a casos extremos onde você acaba "lutando" contra a ferramenta. Considere estes cenários: - `<span className="active"></span>` é extraído? (É uma string, mas provavelmente uma classe). - `<span status="pending"></span>` é extraído? (É um valor de prop). - `<span>{"Hello World"}</span>` é extraído? (É uma expressão JS). - `<span>Hello {name}. How are you?</span>` é extraído? (Interpolação é complexa). - `<span aria-label="Image of cat"></span>` é extraído? (Atributos de acessibilidade precisam de tradução). - O `<span data-testid="my-element"></span>` é extraído? (IDs de teste NÃO devem ser traduzidos). - O `<MyComponent errorMessage="An error occurred" />` é extraído? - O `<p>This is a paragraph{" "}\n containing multiple lines</p>` é extraído? - O resultado da função `<p>{getStatusMessage()}</p>` é extraído? - O `<div>{isLoading ? "The page is loading" : <MyComponent/>} </div>` é extraído? - Um ID de produto como `<span>AX-99</span>` é extraído? Inevitavelmente, você acaba adicionando comentários específicos (como `// ignore-translation`, ou props específicas como `data-compiler-ignore="true"`) para evitar que isso quebre a lógica da sua aplicação. ### Como o Intlayer lida com essa complexidade? Intlayer utiliza uma abordagem mista para detectar se um campo deve ser extraído para tradução, tentando minimizar falsos positivos: 1. **Análise AST:** Verifica o tipo do elemento (por exemplo, distinguindo entre um `reactNode`, um `label` ou uma prop `title`). 2. **Reconhecimento de Padrões:** Detecta se a string está capitalizada ou inclui espaços, sugerindo que provavelmente é um texto legível por humanos e não um identificador de código. ### O Limite Rígido para Dados Dinâmicos A extração pelo compilador depende de **análise estática**. Ele deve ver a string literal no seu código para gerar um ID estável. Se a sua API retornar uma string de código de erro como `server_error`, você não poderá traduzi-la com um compilador porque o compilador não sabe que essa string existe em tempo de build. Você será forçado a construir um sistema secundário "apenas em tempo de execução" apenas para dados dinâmicos. ### Falta de chunking Certos compiladores não fragmentam as traduções por página. Se o seu compilador gerar um arquivo JSON grande por idioma (por exemplo, `./lang/en.json`, `./lang/fr.json`, etc.), você provavelmente acabará carregando conteúdo de todas as suas páginas para uma única página visitada. Além disso, cada componente que usa seu conteúdo provavelmente será hidratado com muito mais conteúdo do que o necessário, o que pode causar problemas de desempenho. Também tenha cuidado ao carregar suas traduções dinamicamente. Se isso não for feito, você carregará conteúdo para todos os idiomas além do atual. > Para ilustrar o problema, considere um site com 10 páginas e 10 idiomas (todos 100% únicos). Você carregaria conteúdo para 99 páginas adicionais (10 × 10 - 1). ### "Explosão de Chunks" e Cascatas de Rede Para resolver o problema do chunking, algumas soluções oferecem chunking por componente, ou até mesmo por chave. No entanto, o problema é apenas parcialmente resolvido. O argumento de venda dessas soluções é frequentemente dizer "Seu conteúdo é tree-shaken." De fato, se você carregar conteúdo estaticamente, sua solução fará tree-shake no conteúdo não utilizado, mas você ainda acabará com conteúdo de todos os idiomas carregado junto com sua aplicação. Então, por que não carregar dinamicamente? Sim, nesse caso você carregará mais conteúdo do que o necessário, mas isso não é sem compensações. Carregar conteúdo dinamicamente isola cada pedaço de conteúdo em seu próprio chunk, que só será carregado quando o componente for renderizado. Isso significa que você fará uma requisição HTTP por bloco de texto. 1.000 blocos de texto na sua página? → 1.000 requisições HTTP para seus servidores. E para limitar o impacto e otimizar o tempo de renderização inicial da sua aplicação, você precisará inserir múltiplos limites de Suspense ou Skeleton Loaders. > Nota: Mesmo com Next.js e SSR, seus componentes ainda serão hidratados após o carregamento, então as requisições HTTP ainda serão feitas. A solução? Adotar uma solução que permita declarar declarações de conteúdo com escopo, como fazem `i18next`, `next-intl` ou `intlayer`. > Nota: `i18next` e `next-intl` exigem que você gerencie manualmente a importação dos namespaces / mensagens para cada página, a fim de otimizar o tamanho do seu bundle. Você deve usar um analisador de bundle como `rollup-plugin-visualizer` (vite), `@next/bundle-analyzer` (next.js) ou `webpack-bundle-analyzer` (React CRA / Angular / etc) para detectar se você está poluindo seu bundle com traduções não utilizadas. ### Sobrecarga de Performance em Tempo de Execução Para tornar as traduções reativas (para que atualizem instantaneamente quando você troca de idioma), o compilador frequentemente injeta hooks de gerenciamento de estado em cada componente. - **O Custo:** Se você renderizar uma lista de 5.000 itens, estará inicializando 5.000 hooks `useState` e `useEffect` apenas para o texto. O React precisa identificar e re-renderizar todos os 5.000 consumidores simultaneamente. Isso causa um bloqueio massivo na "Main Thread", congelando a interface durante a troca. Isso consome memória e ciclos de CPU que bibliotecas declarativas (que normalmente usam um único provedor de Context) economizam. > Note que o problema é semelhante para outros frameworks além do React. ## A Armadilha: Vendor Lock-in Tenha cuidado ao escolher uma solução i18n que permita a extração ou migração das chaves de tradução. No caso de uma biblioteca declarativa, seu código-fonte contém explicitamente sua intenção de tradução: estas são suas chaves, e você as controla. Se quiser mudar de biblioteca, geralmente só precisa atualizar a importação. Com uma abordagem de compilador, seu código-fonte pode ser apenas texto em inglês simples, sem nenhum vestígio da lógica de tradução: tudo está oculto na configuração da ferramenta de build. Se esse plugin deixar de ser mantido ou você quiser mudar de solução, pode ficar preso. Não há uma maneira fácil de "ejetar": não existem chaves utilizáveis no seu código, e você pode precisar re-gerar todas as suas traduções para uma nova biblioteca. Algumas soluções também oferecem serviços de geração de tradução. Sem mais créditos? Sem mais traduções. Os compiladores frequentemente fazem hash do texto (por exemplo, `"Hello World"` -> `x7f2a`). Seus arquivos de tradução ficam parecidos com `{ "x7f2a": "Hola Mundo" }`. A armadilha: se você trocar de biblioteca, a nova biblioteca vê `"Hello World"` e procura por essa chave. Ela não vai encontrar porque seu arquivo de tradução está cheio de hashes (`x7f2a`). ### Bloqueio de Plataforma Ao escolher uma abordagem baseada em compilador, você se prende à plataforma subjacente. Por exemplo, certos compiladores não estão disponíveis para todos os bundlers (como Vite, Turbopack ou Metro). Isso pode tornar as migrações futuras difíceis, e você pode precisar adotar múltiplas soluções para cobrir todas as suas aplicações. ## O Outro Lado: Riscos da Abordagem Declarativa Para ser justo, a forma tradicional declarativa também não é perfeita. Ela tem seu próprio conjunto de "armadilhas". 1. **Inferno dos Namespaces:** Você frequentemente precisa gerenciar manualmente quais arquivos JSON carregar (`common.json`, `dashboard.json`, `footer.json`). Se você esquecer algum, o usuário verá as chaves brutas. 2. **Carregamento excessivo:** Sem uma configuração cuidadosa, é muito fácil carregar acidentalmente _todas_ as suas chaves de tradução para _todas_ as páginas no carregamento inicial, inchando o tamanho do seu bundle. 3. **Desalinhamento de sincronização:** É comum que chaves permaneçam no arquivo JSON muito tempo depois do componente que as utiliza ter sido deletado. Seus arquivos de tradução crescem indefinidamente, cheios de "chaves zumbis". ## O Meio-termo do Intlayer É aqui que ferramentas como o **Intlayer** estão tentando inovar. O Intlayer entende que, embora os compiladores sejam poderosos, a mágica implícita é perigosa. O Intlayer oferece uma abordagem mista, permitindo que você se beneficie das vantagens de ambas as abordagens: gerenciamento declarativo de conteúdo, também compatível com seu compilador para economizar tempo de desenvolvimento. E mesmo que você não use o compilador Intlayer, o Intlayer oferece um comando `transform` (também acessível usando a extensão VSCode). Em vez de apenas fazer mágica na etapa oculta de build, ele pode realmente **reescrever o código do seu componente**. Ele escaneia seu texto e o substitui por declarações explícitas de conteúdo na sua base de código. Isso lhe dá o melhor dos dois mundos: 1. **Granularidade:** Você mantém suas traduções próximas aos seus componentes (melhorando a modularidade e o tree-shaking). 2. **Segurança:** A tradução se torna código explícito, não mágica oculta em tempo de build. 3. **Sem Lock-in:** Como o código é transformado em uma estrutura declarativa dentro do seu repositório, você pode facilmente pressionar tab, ou usar o copilot do seu IDE, para gerar suas declarações de conteúdo, sem esconder lógica em um plugin do webpack. ## Conclusão Então, qual você deve escolher? **Se você está construindo um MVP, ou quer avançar rapidamente:** A abordagem baseada em compilador é uma escolha válida. Ela permite que você avance incrivelmente rápido. Você não precisa se preocupar com estruturas de arquivos ou chaves. Você apenas constrói. A dívida técnica é um problema para o "Você do Futuro". **Se você é um Desenvolvedor Júnior, ou não se importa com otimização:** Se você quer o mínimo de gerenciamento manual, uma abordagem baseada em compilador provavelmente é a melhor. Você não precisará lidar com chaves ou arquivos de tradução - apenas escreva o texto, e o compilador automatiza o resto. Isso reduz o esforço de configuração e os erros comuns de i18n ligados a etapas manuais. **Se você está internacionalizando um projeto existente que já inclui milhares de componentes para refatorar:** Uma abordagem baseada em compilador pode ser uma escolha pragmática aqui. A fase inicial de extração pode economizar semanas ou meses de trabalho manual. No entanto, considere usar uma ferramenta como o comando `transform` do Intlayer, que pode extrair strings e convertê-las em declarações explícitas de conteúdo declarativo. Isso oferece a velocidade da automação enquanto mantém a segurança e a portabilidade de uma abordagem declarativa. Você obtém o melhor dos dois mundos: migração inicial rápida sem dívida arquitetural a longo prazo. **Se você está construindo uma Aplicação Profissional, de Nível Empresarial:** Magia geralmente é uma má ideia. Você precisa de controle. - Você precisa lidar com dados dinâmicos de backends. - Você precisa garantir desempenho em dispositivos de baixo custo (evitando explosões de hooks). - Você precisa garantir que não fique preso a uma ferramenta de build específica para sempre. Para aplicativos profissionais, o **Gerenciamento Declarativo de Conteúdo** (como Intlayer ou bibliotecas consolidadas) continua sendo o padrão ouro. Ele separa suas preocupações, mantém sua arquitetura limpa e garante que a capacidade do seu aplicativo de falar múltiplos idiomas não dependa de um compilador "caixa-preta" tentando adivinhar suas intenções.