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 e Variants.

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/react-intl
• @intlayer/next-i18next
• @intlayer/vue-i18n
• @intlayer/lingui

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

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",  item: 1,  content: {    question: t({ en: "What is Intlayer?", fr: "Qu'est-ce qu'Intlayer ?" }),    answer: t({ en: "An i18n toolkit.", fr: "Une boîte à outils i18n." }),  },} satisfies Dictionary;

import { t, type Dictionary } from "intlayer";export default {  key: "faq",  item: 2,  content: {    question: t({ en: "Is it free?", fr: "Est-ce gratuit ?" }),    answer: t({ en: "Yes, open-source.", fr: "Oui, open-source." }),  },} satisfies Dictionary;

Uso:

// Fetch all items as an arrayconst allFaqs = useIntlayer("faq"); // -> { question: string, answer: string }[]// Fetch a single item by indexconst faq = useIntlayer("faq", { item: 2 }); // -> { question: string, answer: string }

2. Variants

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

Variantes de string (ex. testes A/B)

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" });

Variantes de objeto (ex. Dynamic Records)

import { t, type Dictionary } from "intlayer";export default {  key: "product-copy",  variant: {    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", {  variant: { id: "prod_123", category: "books" },});

Vite Plugin: Compilador Agrupado & Proxy

O plugin Vite intlayer() agora agrupa o compilador e o proxy de roteamento de localidade diretamente, então a maioria dos projetos precisa apenas de um único plugin em vite.config.ts:

import { defineConfig } from "vite";import { intlayer } from "vite-intlayer";export default defineConfig({  plugins: [intlayer()],});

• Compilador: Ativa automaticamente quando compiler.enabled é definido como true e um caminho compiler.output é configurado. Você não precisa mais registrar intlayerCompiler() separadamente.
• Proxy: Ativa automaticamente com base na nova opção routing.enableProxy (true por padrão). Ele conecta o middleware de detecção de localidade / redirecionamento / reescrita em desenvolvimento, visualização e SSR de produção. Você não precisa mais registrar intlayerProxy() separadamente.

Opção routing.enableProxy

Uma nova opção routing.enableProxy controla se o proxy de roteamento de locale está conectado. O padrão é true. Desative-o quando quiser lidar com o roteamento de locale você mesmo:

import type { IntlayerConfig } from "intlayer";const config: IntlayerConfig = {  routing: {    enableProxy: false, // Padrão: true  },};export default config;

Os plugins standalone intlayerCompiler() e intlayerProxy() permanecem exportados para configurações avançadas. Registrá-los junto com intlayer() é seguro — cada plugin se deduplica e é executado apenas uma vez.

Compilador desativado por padrão

A partir do Intlayer v9, o compilador está desativado por padrão (compiler.enabled agora tem o valor padrão false). Para ativar a extração dos seus arquivos .content.ts em tempo de build, defina compiler.enabled: true na sua configuração:

import type { IntlayerConfig } from "intlayer";const config: IntlayerConfig = {  compiler: {    enabled: true, // Padrão: false — necessário para ativar o compilador desde a v9    output: ({ fileName }) => `./${fileName}.content.ts`,  },};export default config;

Quando o compilador está desativado, o Intlayer pula a etapa de extração em tempo de build e depende dos dicionários que você já declarou. Ative-o apenas quando quiser que o plugin do bundler (@intlayer/swc, @intlayer/babel ou o plugin Vite intlayer()) extraia o conteúdo automaticamente.

React Native: importações de um único pacote

Em um aplicativo React Native ou Expo, você não precisa mais alternar entre react-intlayer e react-native-intlayer. O pacote react-native-intlayer agora reexporta toda a API do react-intlayer (hooks, utilitários e os subcaminhos /format, /html e /markdown), e seu IntlayerProvider aplica automaticamente os polyfills do React Native.

Importe tudo do único pacote react-native-intlayer:

import {  IntlayerProvider,  useIntlayer,  useLocale,} from "react-native-intlayer";

npm install intlayer react-native-intlayer

Importar do react-intlayer continua funcionando, mas react-native-intlayer agora é o ponto de entrada único recomendado para React Native — seu provider inclui os polyfills que o provider do react-intlayer (orientado para web) não possui.

SDK do CMS: use o Intlayer como um banco de dados de conteúdo headless

O Intlayer v9 traz um SDK limpo e com autenticação automática em @intlayer/api para interagir com o CMS de forma programática — buscar projetos, buscar dicionários e enviá-los ou atualizá-los a partir do seu próprio servidor, scripts ou CI. A autenticação (OAuth2 client_credentials) é tratada e renovada para você.

O SDK é dividido em duas importações separadas, para que seu bundle inclua apenas os domínios que você realmente usa:

1. createIntlayerCMS — um autenticador leve que guarda as credenciais e o token gerenciado (nenhum cliente de domínio incluído).
2. dictionaryEndpoint, projectEndpoint, … — vinculadores de endpoint por domínio, cada um importado de seu próprio subcaminho.

import { createIntlayerCMS } from "@intlayer/api";import { dictionaryEndpoint } from "@intlayer/api/dictionary";// A configuração é opcional: as credenciais recorrem a INTLAYER_CLIENT_ID /// INTLAYER_CLIENT_SECRET resolvidos por `@intlayer/config/built`.const cms = createIntlayerCMS();// Leituraconst { data: dictionaries } = await dictionaryEndpoint(cms).getDictionaries();// Escrita — use o CMS como um banco de dadosawait dictionaryEndpoint(cms).pushDictionaries([myDictionary]);

Segurança: as credenciais do CMS concedem acesso de escrita ao seu conteúdo. Crie o autenticador sempre no lado do servidor — nunca envie clientId / clientSecret para o navegador.

Auto-hospedagem

O Intlayer v9 traz suporte de primeira classe para executar sua própria instância do Intlayer com um único comando — sem necessidade de conta no Intlayer Cloud.

curl -fsSL https://intlayer.org/install.sh | sh

O instalador baixa um docker-compose.yml e um .env, gera automaticamente os secrets necessários e executa docker compose up -d. Tudo — o dashboard, a API, o banco de dados, o armazenamento de objetos e o e-mail transacional — roda localmente em contêineres.

Serviços incluídos

O Chromium (usado para geração de capturas de tela com Puppeteer) está incluído na imagem do backend — nenhum contêiner adicional é necessário.

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:

• Compilador desativado por padrão: compiler.enabled agora tem o valor padrão false. Se você depende da extração dos seus arquivos .content.ts em tempo de build, defina compiler.enabled: true no seu intlayer.config.ts.
• Plugin Vite: O compilador e o proxy de roteamento de locale agora estão integrados em intlayer(). Se você registrou anteriormente intlayerCompiler() ou intlayerProxy() manualmente, pode removê-los — eles são deduplicados automaticamente, então mantê-los não causa problemas. Use routing.enableProxy: false para desativar o proxy.
• 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 }. 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.
• React Native: react-native-intlayer agora reexporta toda a API do react-intlayer. Em um aplicativo React Native, importe tudo de react-native-intlayer e remova a dependência direta de react-intlayer. Os imports existentes de react-intlayer continuam funcionando.

Links úteis

• Guia de Compat Adapter Packages
• Dicionários Dinâmicos - Collections & Variants
• Referência de Configuração
• SDK do CMS - Acesso programático com @intlayer/api
• Guia de Auto-hospedagem