Skip to main content

Potpun vodič za Next.js internacionalizaciju

Podesite next-intl sa App Router, konfigurišite usmeravanje lokala i automatizujte prevode pomoću AI.

1

Instalirajte next-intl

next-intl je jedan paket koji obrađuje usmeravanje lokala, učitavanje poruka i hook funkcije prevoda za Next.js App Router.

Terminal
npm install next-intl
Zašto next-intl umesto next-i18next? next-intl je napravljen za App Router i serverske komponente. next-i18next je osmišljen za Pages Router i ima ograničenu podršku za App Router.
2

Napravite i18n konfiguraciju zahteva

Napravite dve datoteke: src/i18n/request.ts za učitavanje poruka i src/i18n/routing.ts za definicije lokala. One određuju kako next-intl razrešava poruke i rute.

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 (podrazumevani bundler u Next.js 15) zahteva experimental.turbo.resolveAlias u next.config.js. Bez toga dobijate grešku „Couldn't find next-intl config file".
3

Konfigurišite middleware

Dodajte middleware.ts za otkrivanje lokala, prepisivanje URL adresa i preusmeravanja. Middleware presreće svaki zahtev i obezbeđuje primenu ispravnog lokala.

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 MORA biti u korenskom direktorijumu projekta, a ne u src/. To je najčešća konfiguraciona greška sa next-intl.
4

Podesite strukturu fascikle [locale]

Premestite rute aplikacije u app/[locale]/. Dodajte generateStaticParams da pri komponovanju napravite stranice za svaki lokal. Tako nastaju URL adrese /en/about, /de/about i druge.

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

export function generateStaticParams() {
  return routing.locales.map((locale) => ({ locale }));
}
MORATE da pozovete setRequestLocale(locale) u svakoj page.tsx i layout.tsx datoteci koja koristi prevode. Bez toga Next.js prelazi na dinamičko prikazivanje i učinak komponovanja se znatno pogoršava.
5

Ažurirajte korenski raspored

Učitajte poruke pomoću getMessages() i prosledite ih u NextIntlClientProvider u korenskom rasporedu lokala. Postavite html atribut lang iz parametra lokala.

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 zahteva izričit prop locale. Njegovo izostavljanje izaziva suptilne greške u klijentskim komponentama koje se teško otklanjaju.
6

Koristite prevode u komponentama

Serverske komponente koriste getTranslations (async, await), a klijentske useTranslations (hook). Izaberite prema mestu prikazivanja komponente — serverske komponente potpuno izostavljaju prevode iz JavaScript paketa.

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')} />;
}
Za prevedeni sadržaj koristite serverske komponente. One uklanjaju tekstove prevoda iz klijentskog JavaScript paketa i skraćuju vreme učitavanja.
7

Dodajte SEO: metapodatke i hreflang

Koristite generateMetadata da napravite naslove i opise stranica za svaki lokal. Dodajte alternates.languages za hreflang oznake kako bi pretraživači otkrili sve jezičke verzije svake stranice.

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}`])
      ),
    },
  };
}
Vercel build može da generiše localhost kao kanonsku URL adresu ako metadataBase nije postavljen. Uvek postavite metadataBase u korenskom rasporedu na produkcioni domen.
8

Obradite stranice greške i nepostojeće stranice

error.tsx i not-found.tsx zahtevaju posebnu obradu jer mogu da se prikažu van uobičajenog rasporeda lokala. Koreni not-found.tsx zahteva sopstveno i18n podešavanje dobavljača da prikaže lokalizovane poruke o greškama.

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 prikazuje lokalizovanu 404 stranicu samo kada u kodu izričito pozovete notFound(). Nepoznate rute bez odgovarajuće stranice prikazuju podrazumevani Next.js 404, a ne lokalizovanu verziju.
9

Automatizujte prevode

Kada završite i18n podešavanje, prevedite datoteke poruka pomoću AI direktno iz IDE okruženja ili koristite i18n Agent CLI u CI/CD pipeline procesu za automatski prevod pri svakom postavljanju.

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)
Koristite next-intl-localechain za pametne rezervne lokale — korisnik pt-BR lokala vidi pt-PT prevode umesto engleskog kada brazilski portugalski nije dostupan.

Automatizujte kvalitet prevoda

Otkrijte nedostajuće ključeve i neispravna mesta za promenljive pomoću i18n-validate pre objavljivanja. Testirajte UI lažnim prevodima pomoću i18n-pseudo pre nego što stignu pravi prevodi.

Alati otvorenog koda za Next.js i18n

Ovi paketi otvorenog koda rešavaju uobičajene probleme u tokovima Next.js internacionalizacije.

next-intl-localechain

Standardni next-intl odmah prelazi na podrazumevani lokal kada prevod nedostaje. Korisnik brazilskog portugalskog vidi engleski umesto potpuno dobrih pt-PT prevoda. next-intl-localechain dodaje pametne rezervne lance — duboko spaja prevode srodnih lokala kako bi regionalni korisnici uvek videli najbliži dostupan prevod.

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'
}));
Automatski duboko spaja prevode u lancima lokala
Ugrađeni lanci za portugalski, španski, francuski, nemački i druge jezike
Neprimetno preskače nedostajuće datoteke poruka bez grešaka
Podešavanje u jednom redu — obavija postojeći getRequestConfig
Pogledajte na GitHub platformi

@i18n-agent/cli

Alat komandne linije za prevođenje Next.js datoteka poruka bez napuštanja terminala. Direktno prevodite datoteke, proveravajte stanje zadatka i preuzimajte rezultate. Radi u CI/CD pipeline procesima sa potvrdom identiteta API ključem radi potpuno automatizovane lokalizacije.

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
Prevodite JSON, YAML, PO i druge i18n formate iz terminala
Spremno za CI/CD — potvrda identiteta promenljivom okruženja za automatizovane pipeline procese
Pratite stanje zadatka, nastavite neuspele zadatke i preuzmite rezultate
Mašinski čitljiv JSON izlaz za skripte i automatizaciju
Pogledajte na GitHub platformi

Uobičajene zamke

„Unable to find next-intl locale"

Middleware nije obuhvatio zahtev. Proverite: da li je middleware.ts u korenu projekta, da li matcher pravilno isključuje statičke datoteke i da li je lokal uključen u konfiguraciju usmeravanja.

Neočekivano dinamičko prikazivanje

setRequestLocale(locale) nedostaje na stranici ili u rasporedu. Bez njega next-intl koristi zaglavlja i kolačiće za otkrivanje lokala, što nameće dinamičko prikazivanje i sprečava statičko generisanje.

Paralelne rute ne rade sa i18n

Paralelne rute (@modal) i rute presretanja ((.)photo) imaju poznate nekompatibilnosti sa dinamičkim segmentom [locale]. Za ove napredne obrasce koristite usmeravanje preko middleware sloja kao zaobilazno rešenje.

Promena jezika gubi trenutnu rutu

Pri promeni lokala sačuvajte trenutnu putanju pomoću usePathname() i zamenite samo segment lokala. Pazite na parametre dinamičke rute — moraju ponovo da se razreše za novi lokal.

Preporučena struktura datoteka

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

Prevedite i:

Isprobajte i18n Agent sada

Pustite datoteku za prevođenje ovde

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

ili kliknite za izbor

Ciljni jezici

Registracija nije potrebnaTrenutna procena

Rezervni lokali sa next-intl-localechain

Kada u regionalnom lokalu kao što je pt-BR nedostaje ključ prevoda, next-intl odmah prelazi na podrazumevani lokal umesto da najpre proveri nadređeni lokal 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`),
});

Pogledajte naš vodič za rezervne lokale za celu listu podržanih sistema i 75 ugrađenih lanaca. Learn more →

Česta pitanja