Capítulo 307 de 456

Internationalization

Core Idea

Next.js (Pages Router, desde v10) tem roteamento i18n embutido, seja por sub-path (/fr/blog) ou por domínio dedicado por locale, complementando libs de tradução como next-intl/react-intl (não substitui elas).

Key Concepts

  • i18n.locales/defaultLocale: config em next.config.js; locale é um UTS Locale Identifier (language-region-script, ex. en-US).
  • Sub-path Routing: locale entra no path (/fr/blog); o defaultLocale não tem prefixo.
  • Domain Routing: cada domínio serve um locale default via i18n.domains, com fallback de outros locales redirecionados pro domínio certo.
  • Automatic Locale Detection: baseado no header Accept-Language, redireciona pro path/domínio do locale detectado ao visitar /; desligável com localeDetection: false.
  • Cookie NEXT_LOCALE: tem prioridade sobre Accept-Language, útil pra language switcher persistente.
  • getStaticPaths com locale: cada path retornado pode especificar locale; sem isso, só o defaultLocale é prerenderizado.
  • Limites: até 100 locales e até 100 domain items na config.
  • Incompatível com output: 'export': roteamento i18n não funciona em static export.

Code Examples

module.exports = {
  i18n: {
    locales: ['en-US', 'fr', 'nl-NL'],
    defaultLocale: 'en-US',
    domains: [
      { domain: 'example.com', defaultLocale: 'en-US' },
      { domain: 'example.nl', defaultLocale: 'nl-NL' },
    ],
  },
}
  • O que demonstra: config combinando lista de locales com domain routing.
export const getStaticPaths = ({ locales }) => {
  return {
    paths: [
      { params: { slug: 'post-1' }, locale: 'en-US' },
      { params: { slug: 'post-1' }, locale: 'fr' },
    ],
    fallback: true,
  }
}
  • O que demonstra: prerender explícito de múltiplas variantes de locale pro mesmo slug.

Reference Tables

EstratégiaComo funcionaURL exemplo
Sub-path RoutingLocale no path/fr/blog
Domain RoutingLocale por domínioexample.fr/blog

Anti-patterns

  • Muitos locales em página getStaticProps não-dinâmica: gera uma versão da página por locale no build; 50 locales × 10 páginas = 500 chamadas de getStaticProps no build, use fallback: true pra mitigar em rotas dinâmicas.
  • Assumir que i18n routing funciona com output: 'export': não funciona, pois não usa a routing layer do Next.js.
  • Usar href já prefixado sem locale={false}: o Next.js tentaria prefixar de novo; usar locale={false} no <Link> quando o href já inclui o locale.

Key Takeaways

  1. i18n routing do Next.js cuida só de roteamento/detecção de locale, não de tradução de strings, isso é papel de uma lib como next-intl.
  2. Domain Routing e Sub-path Routing são mutuamente combináveis via config domains.
  3. Cookie NEXT_LOCALE sobrepõe Accept-Language pra persistir escolha do usuário.
  4. Rotas dinâmicas com muitos locales devem usar fallback: true/blocking pra não explodir o tempo de build.

Connects To

  • ch305 ISR: fallback: true/blocking em getStaticPaths funciona igual pra path e pra locale.
AnteriorInstrumentationPróximoLazy Loading