Skip to main content

Kompletní průvodce internacionalizací v Next.js

Nastavte next-intl s App Routerem, nakonfigurujte routování locale a automatizujte překlady pomocí AI.

1

Nainstalujte next-intl

next-intl je jediný balíček, který řeší routování locale, načítání messages a překladové hooky pro Next.js App Router.

Terminal
npm install next-intl
Proč next-intl místo next-i18next? next-intl je postavený pro App Router a server components. next-i18next byl navržen pro Pages Router a má omezenou podporu App Routeru.
2

Vytvořte i18n Request Config

Vytvořte dva soubory: src/i18n/request.ts pro načítání messages a src/i18n/routing.ts pro definice locale. Tyto soubory konfigurují, jak next-intl vyhodnocuje messages a routování.

src/i18n/routing.ts
// src/i18n/routing.ts
import { defineRouting } from 'next-intl/routing';
import { createNavigation } from 'next-intl/navigation';

export const routing = defineRouting({
  locales: ['en', 'de', 'ja', 'es'],
  defaultLocale: 'en',
  localePrefix: 'as-needed',  // /about for en, /de/about for de
});

export const { Link, redirect, usePathname, useRouter } =
  createNavigation(routing);
Turbopack (výchozí bundler v Next.js 15) vyžaduje experimental.turbo.resolveAlias ve Vašem next.config.js. Bez toho budete dostávat chyby "Couldn't find next-intl config file".
3

Nakonfigurujte middleware

Přidejte middleware.ts pro detekci locale, přepisování URL a přesměrování. Middleware zachytí každý požadavek a zajistí použití správného locale.

middleware.ts
// middleware.ts  <- Must be in project ROOT, not src/
import createMiddleware from 'next-intl/middleware';
import { routing } from './src/i18n/routing';

export default createMiddleware(routing);

export const config = {
  matcher: ['/((?!api|_next|.*\\..*).*)'],
};
middleware.ts MUSÍ být v kořenovém adresáři projektu, ne uvnitř src/. To je zdaleka nejčastější konfigurační chyba u next-intl.
4

Nastavte strukturu složek [locale]

Přesuňte routy aplikace do app/[locale]/. Přidejte generateStaticParams pro vygenerování stránek pro každé locale při buildu. Tím vytvoříte strukturu URL /en/about, /de/about atd.

app/[locale]/layout.tsx
// app/[locale]/layout.tsx
import { routing } from '@/i18n/routing';

export function generateStaticParams() {
  return routing.locales.map((locale) => ({ locale }));
}
V každém page.tsx a layout.tsx, které používají překlady, MUSÍTE zavolat setRequestLocale(locale). Bez toho Next.js přejde na dynamické renderování a výkon buildu se výrazně zhorší.
5

Aktualizujte root layout

Načtěte messages pomocí getMessages() a předejte je do NextIntlClientProvider v kořenovém layoutu pro dané locale. Nastavte atribut html lang z parametru locale.

app/[locale]/layout.tsx
// app/[locale]/layout.tsx
import { NextIntlClientProvider } from 'next-intl';
import { getMessages, setRequestLocale } from 'next-intl/server';
import { routing } from '@/i18n/routing';
import { notFound } from 'next/navigation';

export function generateStaticParams() {
  return routing.locales.map((locale) => ({ locale }));
}

export default async function LocaleLayout({
  children,
  params,
}: {
  children: React.ReactNode;
  params: { locale: string };
}) {
  const { locale } = await params;
  if (!routing.locales.includes(locale as any)) notFound();

  setRequestLocale(locale);
  const messages = await getMessages();

  return (
    <html lang={locale}>
      <body>
        <NextIntlClientProvider locale={locale} messages={messages}>
          {children}
        </NextIntlClientProvider>
      </body>
    </html>
  );
}
NextIntlClientProvider vyžaduje explicitní prop locale. Jeho vynechání způsobuje nenápadné chyby v client components, které se obtížně ladí.
6

Používejte překlady v komponentách

Server components používají getTranslations (async, await). Client components používají useTranslations (hook). Vyberte podle toho, kde se komponenta renderuje — server components udrží překlady zcela mimo JavaScript bundle klienta.

app/[locale]/page.tsx
// Server Component (default)
import { getTranslations, setRequestLocale } from 'next-intl/server';

export default async function AboutPage({
  params,
}: { params: { locale: string } }) {
  const { locale } = await params;
  setRequestLocale(locale);
  const t = await getTranslations('AboutPage');

  return <h1>{t('title')}</h1>;
}

// Client Component ('use client')
'use client';
import { useTranslations } from 'next-intl';

export default function SearchBar() {
  const t = useTranslations('SearchBar');
  return <input placeholder={t('placeholder')} />;
}
Upřednostňujte server components pro přeložený obsah. Udrží překladové řetězce mimo client JavaScript bundle a zkrátí dobu načítání pro uživatele.
7

Přidejte SEO: metadata a hreflang

Použijte generateMetadata pro vytváření názvů a popisů stránek specifických pro locale. Přidejte alternates.languages pro tagy hreflang, aby vyhledávače objevily všechny jazykové verze každé stránky.

app/[locale]/layout.tsx
// app/[locale]/layout.tsx or any page.tsx
import { getTranslations } from 'next-intl/server';
import { routing } from '@/i18n/routing';

export async function generateMetadata({
  params,
}: { params: { locale: string } }) {
  const { locale } = await params;
  const t = await getTranslations({ locale, namespace: 'Metadata' });

  return {
    title: t('title'),
    description: t('description'),
    alternates: {
      languages: Object.fromEntries(
        routing.locales.map((l) => [l, `/${l}`])
      ),
    },
  };
}
Na Vercelu může build vygenerovat localhost jako canonical URL, pokud není nastaven metadataBase. Vždy nastavte metadataBase v root layoutu na produkční doménu.
8

Řešte chybové stránky a stránky not-found

error.tsx a not-found.tsx vyžadují speciální zacházení, protože se mohou renderovat mimo běžný layout pro locale. Kořenový not-found.tsx potřebuje vlastní nastavení i18n provideru, aby zobrazil lokalizované chybové zprávy.

app/[locale]/error.tsx
// app/[locale]/error.tsx
'use client';
import { useTranslations } from 'next-intl';

export default function Error() {
  const t = useTranslations('Error');
  return (
    <div>
      <h1>{t('title')}</h1>
      <p>{t('description')}</p>
    </div>
  );
}

// app/not-found.tsx (root level -- needs own provider)
import { routing } from '@/i18n/routing';

export default async function GlobalNotFound() {
  return (
    <html lang={routing.defaultLocale}>
      <body>
        <h1>404 - Page Not Found</h1>
      </body>
    </html>
  );
}
Next.js vykreslí Vaši lokalizovanou stránku 404 pouze tehdy, když je ve Vašem kódu explicitně zavolána notFound(). Neznámé routy bez odpovídající stránky zobrazí výchozí 404 z Next.js, nikoli Vaši lokalizovanou verzi.
9

Automatizujte překlady

Po dokončení nastavení i18n přeložte své soubory messages pomocí AI přímo z IDE, nebo použijte i18n Agent CLI ve Vašem CI/CD pipeline pro automatizovaný překlad při každém deployi.

Terminal
# In your IDE, ask your AI assistant:
> Translate messages/en.json to German, Japanese, and Spanish

✓ messages/de.json created (1.1s)
✓ messages/ja.json created (1.4s)
✓ messages/es.json created (1.0s)
Použijte next-intl-localechain pro inteligentní fallback locale — uživatel pt-BR uvidí překlady pt-PT místo fallbacku do angličtiny, pokud brazilská portugalština není k dispozici.

Automatizujte kontrolu kvality překladu

Odhalte chybějící klíče a rozbité zástupné znaky ještě před vydáním pomocí i18n-validate. Otestujte své UI s falešnými překlady pomocí i18n-pseudo ještě předtím, než dorazí skutečné překlady.

Open-source nástroje pro Next.js i18n

Tyto open-source balíčky řeší běžné slabiny v pracovních postupech internacionalizace v Next.js.

next-intl-localechain

Standardní next-intl při chybějícím překladu přechází rovnou na Vaše výchozí locale. Uživatel z Brazílie pak vidí angličtinu místo zcela použitelných překladů pt-PT. next-intl-localechain přidává inteligentní fallback řetězce — provádí deep-merge překladů z příbuzných locale, takže regionální uživatelé vždy uvidí nejbližší dostupný překlad.

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

export default getRequestConfig(withLocaleChain({
  loadMessages: (locale) =>
    import(`../../messages/${locale}.json`).then(m => m.default),
  defaultLocale: 'en'
}));
Automaticky provádí deep-merge překladů napříč řetězci locale
Vestavěné řetězce pro portugalštinu, španělštinu, francouzštinu, němčinu a další
Bezchybně přeskočí chybějící soubory messages
Nastavení na jeden řádek — obalí Vaše stávající getRequestConfig
Zobrazit na GitHubu

@i18n-agent/cli

Nástroj příkazové řádky pro překlad souborů messages v Next.js bez opuštění terminálu. Překládejte soubory přímo, kontrolujte stav úloh a stahujte výsledky. Funguje v CI/CD pipelines s autentizací pomocí API klíče pro plně automatizované lokalizační workflow.

Terminal
# Install the CLI
npm install -g @i18n-agent/cli

# Authenticate
i18nagent login

# Translate your message files
i18nagent translate ./messages/en.json --lang de,ja,es

# Or use in CI/CD with an API key
export I18N_AGENT_API_KEY=your-key-here
i18nagent translate ./messages/en.json --lang de,ja,es
Překládejte JSON, YAML, PO a další formáty i18n z terminálu
Připraveno pro CI/CD — autentizace přes proměnnou prostředí pro automatizované pipelines
Sledujte stav úloh, obnovujte selhané úlohy a stahujte výsledky
Strojově čitelný JSON výstup pro skriptování a automatizaci
Zobrazit na GitHubu

Časté problémy

"Unable to find next-intl locale"

Middleware neodpovídal požadavku. Zkontrolujte: je middleware.ts v kořenovém adresáři projektu? Vylučuje vzor matcheru správně statické soubory? Je locale zahrnuté v routing konfiguraci?

Nečekané dynamické renderování

Na stránce nebo v layoutu chybí setRequestLocale(locale). Bez něj next-intl detekuje locale z hlaviček/cookies, což vynutí dynamické renderování a znemožní statické generování.

Paralelní routy se lámou s i18n

Paralelní routy (@modal) a intercepting routy ((.)photo) mají známé nekompatibility s dynamickým segmentem [locale]. Pro tyto pokročilé routing vzory použijte jako workaround middleware-based routing.

Přepínání jazyka ztrácí aktuální routu

Při přepínání locale zachovejte aktuální pathname pomocí usePathname() a nahraďte pouze segment locale. Buďte opatrní u parametrů dynamických rout — pro nové locale je potřeba je znovu vyhodnotit.

Doporučená struktura souborů

Project Structure
my-nextjs-app/
├── middleware.ts              # Locale routing (project root!)
├── next.config.mjs
├── messages/
│   ├── en.json                # Source messages
│   ├── de.json
│   └── ja.json
├── src/
│   ├── i18n/
│   │   ├── request.ts         # Message loading config
│   │   └── routing.ts         # Locale definitions
│   └── app/
│       └── [locale]/
│           ├── layout.tsx     # Root locale layout
│           ├── page.tsx       # Home page
│           ├── error.tsx      # Localized error page
│           ├── not-found.tsx  # Localized 404
│           └── about/
│               └── page.tsx
└── package.json

Přeložit také:

Vyzkoušejte i18n Agent nyní

Sem přetáhněte svůj překladový soubor

JSON, YAML, PO, XML, CSV, Markdown, Properties

nebo klikněte a vyberte soubor

Cílové jazyky

Bez registraceOkamžitý odhad

Fallback pro locale s next-intl-localechain

Když v regionální lokalitě, jako je pt-BR, chybí klíč překladu, next-intl přeskočí rovnou na výchozí lokalitu místo toho, aby nejdřív zkontroloval nadřazenou lokalitu pt.

Terminal
npm install next-intl-localechain
Configuration
import { withLocaleChain } from 'next-intl-localechain';

export default withLocaleChain({
  fallbacks: {
    'pt-BR': ['pt', 'en'],
    'zh-Hant-HK': ['zh-Hant', 'zh', 'en'],
  },
  defaultLocale: 'en',
  loadMessages: (locale) => import(`./messages/${locale}.json`),
});

Kompletní seznam podporovaných frameworků a 75 vestavěných řetězců najdete v našem průvodci pro fallback locale. Learn more →

Často kladené otázky