Novo Intlayer v9 - O que há de novo?

Bem-vindo ao Intlayer v9! Este grande lançamento marca um marco enorme na simplificação do caminho de migração para o Intlayer com Compat Adapter Packages para as principais bibliotecas de i18n (react-i18next, next-intl, vue-i18n, etc.) e adiciona suporte para estruturas de conteúdo ricas: Collections, Variants e Dynamic Records.

Tabela de conteúdos

Compat Adapter Packages

Migrar para o Intlayer a partir de bibliotecas i18n populares agora é mais fácil do que nunca. Criamos cinco pacotes de compatibilidade que expõem as mesmas APIs públicas que as bibliotecas i18n padrão, mas delegam todo o trabalho de tradução para o Intlayer em runtime.

Expor a Mesma API Pública com Strict Typing

Ao substituir os imports, você obtém todos os benefícios do Intlayer (incluindo type safety em tempo de compilação contra seus dicionários reais) com o mínimo de alterações no código:

• @intlayer/i18next
• @intlayer/react-i18next
• @intlayer/next-intl
• @intlayer/next-i18next
• @intlayer/vue-i18n

Por exemplo, basta alterar:

import { useTranslation } from "react-i18next";

para:

import { useTranslation } from "@intlayer/react-i18next";

Suas chaves agora serão strictly typed (fortemente tipadas) contra seus dicionários Intlayer, oferecendo auto-complete completo de dot-path na sua IDE!

Plugins de Alias de Bundler (Vite, Next.js, Turbopack)

Para permitir a migração sem reescrever todas as suas declarações de import manualmente, cada pacote de compatibilidade inclui um plugin de bundler personalizado (Vite ou Next.js) sob o subcaminho /plugin.

Esses plugins reescrevem automaticamente os imports existentes (ex: react-i18next ou next-intl) para seus equivalentes @intlayer/* em tempo de build.

Exemplo de Next.js (Webpack / Turbopack)

Em vez de withIntlayer, envolva sua configuração do Next.js com o plugin de compatibilidade:

import { createNextI18nPlugin } from "@intlayer/next-i18next/plugin";import type { NextConfig } from "next";const withIntlayer = createNextI18nPlugin();const nextConfig: NextConfig = {};export default withIntlayer(nextConfig);

Exemplo de Vite (React, Vue, Solid, Svelte)

import vueI18nVitePlugin from "@intlayer/vue-i18n/plugin";export default defineConfig({  plugins: [vueI18nVitePlugin()],});

Mutualized Runtime Resolver

Todos os adaptadores de compatibilidade agora roteiam a resolução de tradução através de um único parser de runtime altamente otimizado: @intlayer/core/messageFormat.

• Interpolate Message: Resolve {{var}} padrão (espaços em branco e dot-paths), argumentos formatados em ICU ({v, number, percent} etc.) e templates simples {var}.
• Message Node Resolver: Resolve nós aninhados: insert(), plural() (regras de plural CLDR), enu() (enumeração), gender(), tags HTML, arrays e nós de funções chamáveis.
• Tokenized Tag Parser: Suporta tags XML/HTML inline e tags numeradas (ex: <1>children</1>) para habilitar renderização de rich-text nativamente.

Especificação de Recursos: Collections, Variants & Dynamic Records

O Intlayer v9 vai além de objetos estáticos de chave-valor, permitindo que os dicionários declarem estruturas de layout dinâmicas que são totalmente tipadas de ponta a ponta.

1. Collections

Defina uma lista gerenciada por CMS de itens ordenados (ex: FAQs, produtos ou listas de blog):

import { t, type Dictionary } from "intlayer";export default {  key: "faq",  content: [    {      question: t({        pt: "O que é o Intlayer?",        en: "What is Intlayer?",        fr: "Qu'est-ce qu'Intlayer ?",      }),      answer: t({        pt: "Um kit de ferramentas i18n.",        en: "An i18n toolkit.",        fr: "Une boîte à outils i18n.",      }),    },  ],} satisfies Dictionary;

Uso:

// Buscar todos os itensconst allFaqs = useIntlayer("faq"); // -> { question: string, answer: string }[]// Buscar um único item por índiceconst faq = useIntlayer("faq", { item: 1 }); // -> { question: string, answer: string }

2. Variants

Entregue testes A/B, cabeçalhos sazonais, feature flags ou landing pages personalizadas:

import { t, type Dictionary } from "intlayer";export default {  key: "hero-banner",  variant: "default",  content: {    control: t({ pt: "Bem-vindo", en: "Welcome", fr: "Bienvenue" }),    black_friday: t({      pt: "Compre agora",      en: "Shop now",      fr: "Acheter maintenant",    }),  },} satisfies Dictionary;

Uso:

const banner = useIntlayer("hero-banner", { variant: "black_friday" });

3. Dynamic Records

Defina dicionários cujas entradas são carregadas dinamicamente em runtime via IDs de consulta:

import { t, type Dictionary } from "intlayer";export default {  key: "product-copy",  meta: {    id: "prod_123",    category: "books",  },  content: {    title: t({ pt: "Código Limpo", en: "Clean Code", fr: "Code Propre" }),  },} satisfies Dictionary;

Uso:

// Busca apenas o item solicitado dinamicamente (requer Suspense)const product = useIntlayer("product-copy", {  id: "prod_123",  category: "books",});

Carregamento Dinâmico & Otimizações de Tamanho de Bundle

Para manter os bundles extremamente pequenos, o Intlayer v9 suporta dynamic lazy loading.

Na sua configuração, defina importMode como 'dynamic' ou 'fetch':

export default {  dictionary: {    importMode: "dynamic", // "static" | "dynamic" | "fetch"  },};

Em tempo de build, o @intlayer/swc e o @intlayer/babel escaneiam seus arquivos e substituem as chamadas de useIntlayer / getIntlayer por wrappers tree-shakeable (useDictionary / useDictionaryDynamic). Apenas o conteúdo necessário para o item da coleção, variante ou locale selecionado é carregado, evitando que seu bundle de produção contenha traduções não utilizadas.

Notas de migração da v8

Se você estiver atualizando da v8, observe que a v9 não inclui breaking changes. Mas aqui estão as principais mudanças:

• Locales & Dialects: Se estiver usando dependências externas de i18n, adicione seus respectivos plugins de compatibilidade na sua configuração ou setup do bundler para reescrever os imports automaticamente.
• Custom Selectors: Ao chamar useIntlayer, o segundo parâmetro agora é reservado para um objeto de opções contendo { locale, item, variant, id }. Se você passava anteriormente uma string de locale diretamente, ainda pode fazer isso, mas o uso do objeto de opções é recomendado para seleções avançadas.

Links úteis

• Guia de Compat Adapter Packages
• Dicionários Dinâmicos - Collections, Variants & Dynamic Records
• Referência de Configuração