O que next-intl faz?
Visão Geral
next-intl é a principal biblioteca de internacionalização (i18n) para o Next.js App Router. Ela gerencia roteamento de locale, tradução de mensagens, formatação de data/número e funciona com componentes tanto do lado do servidor quanto do cliente. Suporta sintaxe de mensagens ICU para plurais e variáveis.
Instruções
Etapa 1: Configuração
npm install next-intl
// i18n/request.ts — Detecção de locale
import { getRequestConfig } from 'next-intl/server'
export default getRequestConfig(async ({ requestLocale }) => {
const locale = await requestLocale || 'en'
return {
locale,
messages: (await import(`../messages/${locale}.json`)).default,
}
})
// messages/en.json
{
"HomePage": {
"title": "Bem-vindo ao {appName}",
"description": "A melhor ferramenta para {count, plural, one {# equipe} other {# equipes}}",
"cta": "Começar"
},
"Dashboard": {
"greeting": "Olá, {name}",
"lastLogin": "Último login: {date, date, medium}"
}
}
// messages/de.json
{
"HomePage": {
"title": "Willkommen bei {appName}",
"description": "Das beste Tool für {count, plural, one {# Team} other {# Teams}}",
"cta": "Jetzt starten"
}
}
Etapa 2: Componentes do Servidor
// app/[locale]/page.tsx — Componente de servidor traduzido
import { useTranslations } from 'next-intl'
export default function HomePage() {
const t = useTranslations('HomePage')
return (
<main>
<h1>{t('title', { appName: 'MyApp' })}</h1>
<p>{t('description', { count: 5000 })}</p>
<a href="/signup">{t('cta')}</a>
</main>
)
}
Etapa 3: Roteamento com Middleware
// middleware.ts — Roteamento de locale
import createMiddleware from 'next-intl/middleware'
export default createMiddleware({
locales: ['en', 'de', 'fr', 'ja'],
defaultLocale: 'en',
localePrefix: 'as-needed', // /de/about mas /about (para en)
})
export const config = { matcher: ['/((?!api|_next|.*\\..*).*)'] }
Diretrizes
- Sintaxe de mensagens ICU:
{count, plural, one {# item} other {# items}}para plurais. - Componentes do servidor: use
useTranslations()diretamente, sem necessidade de contexto. - Componentes do cliente: envolva com
NextIntlClientProvider. - Mantenha as chaves de mensagens organizadas por página/componente para facilitar a manutenção.
- Use
localePrefix: 'as-needed'para evitar o prefixo /en/ para o locale padrão.