Skip to main content

Kompletný sprievodca internacionalizáciou v Next.js

Nastavte next-intl s App Routerom, nakonfigurujte smerovanie podľa jazykového prostredia a automatizujte preklady pomocou AI.

1

Nainštalujte next-intl

next-intl je samostatný balík, ktorý zabezpečuje smerovanie podľa jazykového prostredia, načítanie správ a prekladové hooky pre Next.js App Router.

Terminal
npm install next-intl
Prečo uprednostniť next-intl pred next-i18next? next-intl je vytvorený pre App Router a serverové komponenty. next-i18next bol navrhnutý pre Pages Router a App Router podporuje len obmedzene.
2

Vytvorte konfiguráciu požiadaviek i18n

Vytvorte dva súbory: src/i18n/request.ts na načítanie správ a src/i18n/routing.ts na definovanie jazykových prostredí. Určujú, ako next-intl vyhľadáva správy a zostavuje trasy.

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 (predvolený nástroj na zostavenie v Next.js 15) vyžaduje experimental.turbo.resolveAlias v súbore next.config.js. Bez neho sa zobrazujú chyby "Couldn't find next-intl config file".
3

Nakonfigurujte middleware

Pridajte middleware.ts, ktorý zabezpečí rozpoznanie jazykového prostredia, prepisovanie URL a presmerovania. Middleware zachytí každú požiadavku a zaistí použitie správneho jazykového prostredia.

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Í byť v koreňovom priečinku projektu, nie v src/. Toto je jednoznačne najčastejšia chyba konfigurácie next-intl.
4

Nastavte štruktúru priečinka [locale]

Presuňte trasy aplikácie do app/[locale]/. Pridajte generateStaticParams, aby sa počas zostavenia vytvorili stránky pre každé jazykové prostredie. Vznikne tak štruktúra URL /en/about, /de/about atď.

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

export function generateStaticParams() {
  return routing.locales.map((locale) => ({ locale }));
}
V každom súbore page.tsx a layout.tsx, ktorý používa preklady, MUSÍTE zavolať setRequestLocale(locale). Bez tohto volania Next.js použije dynamické vykresľovanie a výkon zostavenia sa výrazne zníži.
5

Aktualizujte koreňový layout

Načítajte správy pomocou getMessages() a odovzdajte ich komponentu NextIntlClientProvider v koreňovom layoute jazykového prostredia. Atribút lang prvku html nastavte podľa parametra jazykového prostredia.

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ý atribút locale. Jeho vynechanie spôsobuje nenápadné chyby v klientskych komponentoch, ktoré sa ťažko diagnostikujú.
6

Použite preklady v komponentoch

Serverové komponenty používajú getTranslations (asynchrónne, await). Klientske komponenty používajú useTranslations (hook). Vyberte si podľa toho, kde sa komponent vykresľuje — serverové komponenty ponechajú preklady úplne mimo balíka JavaScript.

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')} />;
}
Pri preloženom obsahu uprednostnite serverové komponenty. Prekladové reťazce sa tak nedostanú do klientskeho balíka JavaScript, čím sa používateľom skráti čas načítania.
7

Pridajte SEO: metadáta a hreflang

Pomocou generateMetadata vytvorte názvy a opisy stránok pre jednotlivé jazykové prostredia. Pridajte alternates.languages pre značky hreflang, aby vyhľadávače našli všetky jazykové verzie každej 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}`])
      ),
    },
  };
}
Ak nie je nastavené metadataBase, zostavenia na Verceli môžu ako kanonickú URL vytvoriť localhost. V koreňovom layoute vždy nastavte metadataBase na produkčnú doménu.
8

Spracujte chybové a nenájdené stránky

Súbory error.tsx a not-found.tsx vyžadujú osobitné spracovanie, pretože sa môžu vykresliť mimo bežného layoutu jazykového prostredia. Koreňový súbor not-found.tsx potrebuje vlastné nastavenie poskytovateľa i18n, aby mohol zobrazovať lokalizované chybové hlásenia.

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šu lokalizovanú stránku 404 iba vtedy, keď vo svojom kóde explicitne zavoláte notFound(). Neznáme trasy bez zodpovedajúcej stránky zobrazia predvolenú stránku 404 systému Next.js, nie Vašu lokalizovanú verziu.
9

Automatizujte preklady

Po dokončení nastavenia i18n môžete súbory so správami prekladať pomocou AI priamo z IDE alebo použiť i18n Agent CLI v pipeline CI/CD na automatizovaný preklad pri každom nasadení.

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žite next-intl-localechain na inteligentný výber náhradného jazykového prostredia — používateľ s pt-BR uvidí namiesto angličtiny preklady pt-PT, keď nie je k dispozícii brazílska portugalčina.

Automatizujte kontrolu kvality prekladov

Pomocou i18n-validate odhaľte chýbajúce kľúče a poškodené zástupné symboly ešte pred publikovaním. Kým budú k dispozícii skutočné preklady, otestujte používateľské rozhranie s fiktívnymi prekladmi pomocou i18n-pseudo.

Nástroje s otvoreným zdrojovým kódom pre i18n v Next.js

Tieto balíky s otvoreným zdrojovým kódom riešia bežné problémy pracovných postupov internacionalizácie v Next.js.

next-intl-localechain

Štandardný next-intl pri chýbajúcom preklade prejde priamo na predvolené jazykové prostredie. Používateľ brazílskej portugalčiny tak uvidí angličtinu namiesto plnohodnotných prekladov pt-PT. next-intl-localechain pridáva inteligentné reťazce náhradných jazykových prostredí — hĺbkovo zlučuje preklady zo súvisiacich jazykových prostredí, aby regionálni používatelia vždy videli najbližší dostupný preklad.

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 hĺbkovo zlučuje preklady v reťazcoch jazykových prostredí
Obsahuje reťazce pre portugalčinu, španielčinu, francúzštinu, nemčinu a ďalšie jazyky
Bez chýb preskočí chýbajúce súbory so správami
Jednoriadkové nastavenie — obalí Vaše existujúce getRequestConfig
Zobraziť na GitHube

@i18n-agent/cli

Nástroj príkazového riadka na preklad súborov so správami Next.js bez opustenia terminálu. Umožňuje priamo prekladať súbory, kontrolovať stav úloh a sťahovať výsledky. Funguje v pipeline CI/CD s autentifikáciou pomocou kľúča API, čo umožňuje plne automatizované pracovné postupy lokalizácie.

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
Prekladá JSON, YAML, PO a ďalšie formáty súborov i18n z terminálu
Pripravené na CI/CD — autentifikácia prostredníctvom premennej prostredia pre automatizované pipeline
Sleduje stav úloh, obnovuje neúspešné úlohy a sťahuje výsledky
Strojovo čitateľný výstup JSON pre skripty a automatizáciu
Zobraziť na GitHube

Bežné úskalia

"Unable to find next-intl locale"

Middleware nezodpovedal požiadavke. Skontrolujte: je middleware.ts v koreňovom priečinku projektu? Vylučuje vzor matcher správne statické súbory? Je jazykové prostredie zahrnuté v konfigurácii smerovania?

Neočakávané dynamické vykresľovanie

Na stránke alebo v layoute chýba setRequestLocale(locale). Bez tohto volania next-intl rozpoznáva jazykové prostredie pomocou hlavičiek alebo súborov cookie, čo si vynúti dynamické vykresľovanie a znemožní statické generovanie.

Paralelné trasy nefungujú s i18n

Paralelné trasy (@modal) a zachytávacie trasy ((.)photo) majú známe problémy s kompatibilitou s dynamickým segmentom [locale]. Pri týchto pokročilých spôsoboch smerovania použite ako náhradné riešenie smerovanie pomocou middleware.

Pri zmene jazyka sa stratí aktuálna trasa

Pri zmene jazykového prostredia zachovajte aktuálnu cestu pomocou usePathname() a nahraďte iba segment jazykového prostredia. Pri dynamických parametroch trasy postupujte opatrne — pre nové jazykové prostredie ich treba opätovne vyhodnotiť.

Odporúčaná štruktúra súborov

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

Prekladajte aj:

Vyskúšajte i18n Agent teraz

Potiahnite súbor na preklad sem

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

alebo kliknite a vyberte súbor

Cieľové jazyky

Bez registrácieOkamžitý odhad

Náhradné jazykové prostredie pomocou next-intl-localechain

Keď v regionálnom jazykovom prostredí, napríklad pt-BR, chýba prekladový kľúč, next-intl prejde priamo na predvolené jazykové prostredie namiesto toho, aby najprv skontroloval nadradené jazykové prostredie 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`),
});

Úplný zoznam podporovaných frameworkov a 75 vstavaných reťazcov nájdete v našom sprievodcovi náhradnými jazykovými prostrediami. Learn more →

Často kladené otázky