Otimizando o Tamanho e Desempenho do Bundle i18n

Um dos desafios mais comuns com soluções tradicionais de i18n que dependem de arquivos JSON é gerenciar o tamanho do conteúdo. Se os desenvolvedores não separarem manualmente o conteúdo em namespaces, os usuários frequentemente acabam baixando traduções para todas as páginas e potencialmente para todos os idiomas apenas para visualizar uma única página.

Por exemplo, uma aplicação com 10 páginas traduzidas em 10 idiomas pode resultar em um usuário baixando o conteúdo de 100 páginas, mesmo que ele precise de apenas uma (a página atual no idioma atual). Isso leva a desperdício de largura de banda e tempos de carregamento mais lentos.

Para detectar isso, você pode usar analisadores de bundle como rollup-plugin-visualizer (vite), @next/bundle-analyzer (next.js) ou webpack-bundle-analyzer (React CRA / Angular / etc).

Intlayer resolve esse problema por meio da otimização em tempo de build. Ele analisa seu código para detectar quais dicionários são realmente usados por componente e reinjeta apenas o conteúdo necessário no seu bundle.

Índice

Como Funciona

Intlayer utiliza uma abordagem por componente. Diferente dos arquivos JSON globais, seu conteúdo é definido junto ou dentro dos seus componentes. Durante o processo de build, o Intlayer:

1. Analisa seu código para encontrar chamadas de useIntlayer.
2. Constrói o conteúdo do dicionário correspondente.
3. Substitui a chamada useIntlayer por código otimizado baseado na sua configuração.

Isso garante que:

• Se um componente não for importado, seu conteúdo não será incluído no bundle (Eliminação de Código Morto).
• Se um componente for carregado de forma lazy, seu conteúdo também será carregado de forma lazy.

Configuração por Plataforma

Next.js

Next.js requer o plugin @intlayer/swc para lidar com a transformação, pois o Next.js utiliza SWC para builds.

Este plugin é instalado por padrão porque plugins SWC ainda são experimentais para Next.js. Isso pode mudar no futuro.

Vite

O Vite utiliza o plugin @intlayer/babel, que está incluído como dependência do vite-intlayer. A otimização está habilitada por padrão.

Webpack

Para habilitar a otimização do bundle com Intlayer no Webpack, você precisa instalar e configurar o plugin Babel (@intlayer/babel) ou SWC (@intlayer/swc) apropriado.

Expo / Lynx

A otimização do bundle ainda não está disponível para esta plataforma. O suporte será adicionado em uma versão futura.

Configuração

Você pode controlar como o Intlayer otimiza seu bundle através da propriedade build no seu arquivo intlayer.config.ts.

import { Locales, type IntlayerConfig } from "intlayer";const config: IntlayerConfig = {  internationalization: {    locales: [Locales.ENGLISH, Locales.FRENCH],    defaultLocale: Locales.ENGLISH,  },  build: {    optimize: true,    importMode: "static", // ou 'dynamic'    traversePattern: ["**/*.{js,ts,mjs,cjs,jsx,tsx}", "!**/node_modules/**"],  },};export default config;

Manter a opção padrão para optimize é recomendado na maioria dos casos.

Veja a documentação de configuração para mais detalhes: Configuração

Opções de Build

As seguintes opções estão disponíveis no objeto de configuração build:

Modos de Importação

A configuração importMode determina como o conteúdo do dicionário é injetado no seu componente.

1. Modo Estático (default)

No modo estático, o Intlayer substitui useIntlayer por useDictionary e injeta o dicionário diretamente no bundle JavaScript.

• Prós: Renderização instantânea (síncrona), zero requisições de rede adicionais durante a hidratação.
• Contras: O bundle inclui traduções para todas as línguas disponíveis para aquele componente específico.
• Ideal para: Aplicações Single Page (SPA).

Exemplo de Código Transformado:

// Seu códigoconst content = useIntlayer("my-key");// Código otimizado (Estático)const content = useDictionary({  key: "my-key",  content: {    nodeType: "translation",    translation: {      en: "My title",      fr: "Mon titre",    },  },});

2. Modo Dinâmico

No modo dinâmico, o Intlayer substitui useIntlayer por useDictionaryAsync. Isso utiliza import() (mecanismo semelhante ao Suspense) para carregar preguiçosamente especificamente o JSON para o locale atual.

• Prós: Tree shaking ao nível do locale. Um usuário visualizando a versão em inglês irá apenas baixar o dicionário em inglês. O dicionário em francês nunca é carregado.
• Contras: Dispara uma requisição de rede (busca de asset) por componente durante a hidratação.
• Melhor para: Blocos grandes de texto, artigos, ou aplicações que suportam muitas línguas onde o tamanho do bundle é crítico.

Exemplo de Código Transformado:

// Seu códigoconst content = useIntlayer("my-key");// Código otimizado (Dinâmico)const content = useDictionaryAsync({  en: () =>    import(".intlayer/dynamic_dictionary/my-key/en.json").then(      (mod) => mod.default    ),  fr: () =>    import(".intlayer/dynamic_dictionary/my-key/fr.json").then(      (mod) => mod.default    ),});

Ao usar importMode: 'dynamic', se você tiver 100 componentes usando useIntlayer em uma única página, o navegador tentará fazer 100 requisições separadas. Para evitar essa "cascata" de requisições, agrupe o conteúdo em menos arquivos .content (por exemplo, um dicionário por seção da página) em vez de um por componente atômico.

Atualmente, importMode: 'dynamic' não é totalmente suportado para Vue e Svelte. Recomenda-se usar importMode: 'static' para esses frameworks até atualizações futuras.

3. Modo Live

Comporta-se de forma semelhante ao modo Dinâmico, mas tenta buscar os dicionários da API Intlayer Live Sync primeiro. Se a chamada à API falhar ou o conteúdo não estiver marcado para atualizações ao vivo, ele recorre à importação dinâmica.

Veja a documentação do CMS para mais detalhes: CMS

Resumo: Estático vs Dinâmico