next-intl-docs

next-intl 4

Este skill cobre next-intl 4.x conforme documentado em https://next-intl.dev/docs/getting-started (docs da versão 4.14.9). Ele contém o que difere do hábito: padrões surpreendentes, armadilhas, APIs legadas e os padrões que a documentação recomenda. Cada afirmação nos arquivos de referência termina com a página de onde foi extraída.

Como navegar

1. Leia o início rápido e as regras rápidas abaixo. Eles capturam os erros mais frequentes.
2. Abra o arquivo de referência que corresponde à tarefa, a partir da tabela no final.
3. Quando o código usar setRequestLocale, requestLocale ou middleware.ts, leia primeiro a tabela "Padrões antigos".

Início rápido (App Router)

O App Router é o caminho recomendado. O Pages Router continua suportado, veja references/setup.md. https://next-intl.dev/docs/getting-started/pages-router

// next.config.ts
import {NextConfig} from 'next';
import createNextIntlPlugin from 'next-intl/plugin';

const nextConfig: NextConfig = {};
const withNextIntl = createNextIntlPlugin();
export default withNextIntl(nextConfig);

https://next-intl.dev/docs/getting-started/app-router

Sem URLs baseadas em locale, src/i18n/request.ts resolve o locale a partir de uma preferência do usuário, um cookie no caso mais simples:

// src/i18n/request.ts
import {cookies} from 'next/headers';
import {getRequestConfig} from 'next-intl/server';

export default getRequestConfig(async () => {
  const store = await cookies();
  const locale = store.get('locale')?.value || 'en';
  return {
    locale,
    messages: (await import(`../../messages/${locale}.json`)).default
  };
});

https://next-intl.dev/docs/getting-started/app-router

// src/app/layout.tsx
import {NextIntlClientProvider} from 'next-intl';
import {getLocale} from 'next-intl/server';

export default async function RootLayout({children}) {
  const locale = await getLocale();
  return (
    <html lang={locale}>
      <body>
        <NextIntlClientProvider>{children}</NextIntlClientProvider>
      </body>
    </html>
  );
}

https://next-intl.dev/docs/getting-started/app-router , https://next-intl.dev/docs/usage/configuration

import {useTranslations} from 'next-intl';
import {getTranslations} from 'next-intl/server';

export function HomePage() {
  const t = useTranslations('HomePage'); // componente não-assíncrono
  return <h1>{t('title')}</h1>;
}

export async function Profile() {
  const t = await getTranslations('ProfilePage'); // componente assíncrono
  return <h1>{t('title')}</h1>;
}

https://next-intl.dev/docs/getting-started/app-router

Para URLs do tipo /en/about, adicione src/i18n/routing.ts, src/proxy.ts, src/i18n/navigation.ts e um segmento [locale] de alto nível: references/routing.md. https://next-intl.dev/docs/routing/setup

Regras rápidas

Configuração

• O plugin encontra i18n/request.ts em src/ ou na raiz do projeto (.ts, .tsx, .js, .jsx). Em outros lugares, passe o caminho: createNextIntlPlugin('./somewhere/else/request.ts'). https://next-intl.dev/docs/getting-started/app-router
• O exemplo da documentação fixa const locale = 'en'. Substitua por uma resolução real (cookie, configuração do usuário ou next/root-params). https://next-intl.dev/docs/getting-started/app-router
• getRequestConfig é executado uma vez por requisição, durante a renderização dos Server Components, então cookies() e headers() funcionam lá. https://next-intl.dev/docs/usage/configuration
• Defina timeZone na configuração de requisição. O padrão é o fuso horário do runtime do servidor. https://next-intl.dev/docs/usage/configuration

Roteamento

• Nomeie o arquivo como src/proxy.ts no Next.js 16. O import permanece createMiddleware de next-intl/middleware. https://next-intl.dev/docs/routing/setup
• Leia o locale com await rootParams.locale() de next/root-params, valide-o com hasLocale(routing.locales, value), senão notFound(). Next.js anterior a 16.3 precisa de experimental.rootParams. https://next-intl.dev/docs/routing/setup
• Importe Link, redirect, usePathname, useRouter e getPathname do seu i18n/navigation.ts em vez de next/link ou next/navigation. https://next-intl.dev/docs/routing/navigation
• Alterne os locales com router.replace(pathname, {locale}) desse módulo. <Link locale> não é pré-carregado, para evitar sobrescrever o cookie de locale. https://next-intl.dev/docs/routing/navigation
• redirect sempre recebe um locale: redirect({href: '/login', locale}). Escreva return redirect(...) para que o TypeScript restrinja o tipo. https://next-intl.dev/docs/routing/navigation
• O matcher padrão ignora caminhos com ponto. Adicione uma entrada explícita para rotas como /users/jane.doe. https://next-intl.dev/docs/routing/middleware

Componentes Client

• NextIntlClientProvider sem a prop messages envia TODAS as mensagens para o cliente. Passe messages={pick(messages, 'Namespace')} ou messages={null} para limitá-las. https://next-intl.dev/docs/environments/server-client-components
• Prefira traduzir em um Server Component e passar os rótulos como props ou children para o Client Component. https://next-intl.dev/docs/environments/server-client-components
• onError e getMessageFallback não podem ser passados de um Server Component. Defina-os em seu próprio provider 'use client' aninhado dentro do provider do servidor, que mantém a herança de locale e mensagens, portanto não os passe manualmente. https://next-intl.dev/docs/usage/configuration

Mensagens

• Chaves e namespaces não podem conter ., o que implica aninhamento. Use JSON aninhado apenas. https://next-intl.dev/docs/usage/translations
• Nomes de argumentos ICU e valores select permitem letras, dígitos e _, sem hífens: mapeie en-GB para en_GB. select precisa de um caso other. https://next-intl.dev/docs/usage/translations
• Tags auto-fecháveis precisam de uma tag de fechamento nas mensagens: <br></br>. https://next-intl.dev/docs/usage/translations
• Use getTranslations({locale, namespace}) em Server Actions, metadados e Route Handlers, onde o locale pode não ser inferido. https://next-intl.dev/docs/environments/actions-metadata-route-handlers

Testes

• Vitest com createNavigation: server.deps.inline: ['next-intl']. Jest: transformIgnorePatterns: ['node_modules/(?!next-intl)/']. next-intl é apenas ESM. https://next-intl.dev/docs/environments/testing

Padrões antigos

Antigo	Atual
src/middleware.ts	src/proxy.ts no Next.js 16, mesmo código createMiddleware
setRequestLocale(locale) no topo de todo layout e página	next/root-params em i18n/request.ts, renderização estática funciona sem ele
getRequestConfig(async ({requestLocale}) => ...)	getRequestConfig(async ({locale}) => ...) com fallback para rootParams.locale()
Chaves de mensagens planas "HomePage.title"	Objetos aninhados {"HomePage": {"title": ...}}
t.raw HTML em dangerouslySetInnerHTML	t.rich (React) ou t.markup (strings), t.raw apenas para ignorar análise, sanitizado

Detalhes: references/routing.md e references/messages.md.

Arquivos de referência

Arquivo	Leia para
references/setup.md	Plugin, configuração de requisição, padrões do provider, locale sem roteamento, armazenamento de mensagens, Pages Router
references/routing.md	defineRouting, segmento [locale], proxy.ts, matcher, next/root-params, renderização estática, localePrefix, domínios, cookie, links alternativos, pathnames localizados, exportação estática, solução de problemas
references/navigation.md	createNavigation, Link, useRouter, usePathname, redirect, getPathname, seletor de idioma, href tipado
references/messages.md	useTranslations, namespaces, plurais e select ICU, rich text, t.markup, t.raw, t.has, arrays, mensagens ausentes, onError, fuso horário, now
references/formatting.md	useFormatter: datas, tempo relativo, intervalos, números, listas, nomes de exibição, skeletons ICU, formatos globais
references/server-and-client.md	Componentes Server vs Client, seleção de mensagens, metadados, Server Actions, Zod, Route Handlers, sitemap, imagens OG, arquivos 404 e de erro
references/extraction.md	useExtracted e getExtracted experimentais, opções experimental do plugin, arquivos PO, pré-compilação, codecs personalizados, monorepos
references/typescript-and-tooling.md	Aumento de AppConfig, argumentos com tipo seguro, testes com Jest e Vitest, Storybook, núcleo use-intl, requisitos de runtime, linting, gerenciamento de tradução, convenções de agentes

Páginas rastreadas: SOURCES.md.