Skip to main content

Celovit vodnik po internacionalizaciji v Next.js

Nastavite next-intl z App Routerjem, določite usmerjanje jezikovnih različic in avtomatizirajte prevode z umetno inteligenco.

1

Namestite next-intl

next-intl je en sam paket, ki za Next.js App Router obravnava usmerjanje jezikovnih različic, nalaganje sporočil in prevajalske hooke.

Terminal
npm install next-intl
Zakaj next-intl namesto next-i18next? next-intl je zgrajen za App Router in strežniške komponente. next-i18next je bil zasnovan za Pages Router in App Router podpira le omejeno.
2

Ustvarite nastavitve zahtev i18n

Ustvarite dve datoteki: src/i18n/request.ts za nalaganje sporočil in src/i18n/routing.ts za opredelitve jezikovnih različic. Obe določata, kako next-intl razrešuje sporočila in poti.

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 (privzeti povezovalnik v Next.js 15) v Vašem next.config.js zahteva experimental.turbo.resolveAlias. Brez tega dobite napake "Couldn't find next-intl config file".
3

Nastavite vmesno programsko opremo

Dodajte middleware.ts, ki obravnava zaznavanje jezikovne različice, prepisovanje naslovov URL in preusmeritve. Vmesna programska oprema prestreže vsako zahtevo in zagotovi uporabo pravilne jezikovne različice.

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 v korenskem imeniku Vašega projekta, ne znotraj src/. To je najpogostejša napaka pri nastavitvi next-intl.
4

Nastavite strukturo map [locale]

Poti aplikacije premaknite v app/[locale]/. Dodajte generateStaticParams, da med gradnjo ustvarite strani za vsako jezikovno različico. Tako nastane struktura naslovov URL /en/about, /de/about itd.

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

export function generateStaticParams() {
  return routing.locales.map((locale) => ({ locale }));
}
V vsaki page.tsx in layout.tsx, ki uporablja prevode, MORATE poklicati setRequestLocale(locale). Brez tega Next.js preide na dinamični izris in učinkovitost Vaše gradnje se občutno zmanjša.
5

Posodobite svojo korensko postavitev

S getMessages() naložite sporočila in jih v korenski jezikovni postavitvi podajte v NextIntlClientProvider. Atribut html lang nastavite iz parametra jezikovne različice.

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 izrecno lastnost locale. Če jo izpustite, to v odjemalskih komponentah povzroči težko odpravljive prikrite napake.
6

Uporabljajte prevode v komponentah

Strežniške komponente uporabljajo getTranslations (async, await), odjemalske pa useTranslations (hook). Izberite glede na mesto izrisa komponente: strežniške komponente prevodov sploh ne vključijo v paket 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')} />;
}
Za prevedeno vsebino dajte prednost strežniškim komponentam. Prevajalska besedila ne pridejo v Vaš odjemalski paket JavaScript, zato se uporabnikom vsebina naloži hitreje.
7

Dodajte SEO: metapodatke in hreflang

Z generateMetadata ustvarite naslove in opise strani za posamezne jezikovne različice. Dodajte alternates.languages za oznake hreflang, da iskalniki odkrijejo vse jezikovne različice vsake strani.

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}`])
      ),
    },
  };
}
Gradnje v Vercelu lahko kot kanonični naslov URL ustvarijo localhost, če metadataBase ni nastavljen. V korenski postavitvi metadataBase vedno nastavite na svojo produkcijsko domeno.
8

Obravnavajte strani z napakami in neobstoječe strani

error.tsx in not-found.tsx potrebujeta posebno obravnavo, ker se lahko izrišeta zunaj običajne jezikovne postavitve. Korenski not-found.tsx potrebuje lastno nastavitev ponudnika i18n, da prikaže lokalizirana sporočila o napakah.

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 Vašo lokalizirano stran 404 izriše samo, kadar v kodi izrecno pokličete notFound(). Neznane poti brez ujemajoče se strani pokažejo privzeto stran 404 iz Next.js, ne Vaše lokalizirane različice.
9

Avtomatizirajte prevode

Ko je nastavitev i18n končana, svoje datoteke sporočil prevedite z umetno inteligenco neposredno iz razvojnega okolja IDE ali pa v pipelineu CI/CD uporabite CLI i18n Agent za samodejno prevajanje ob vsaki uvedbi.

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)
Za pametne nadomestne jezikovne različice uporabite next-intl-localechain: uporabnik pt-BR vidi prevode pt-PT, namesto da bi ob nerazpoložljivi brazilski portugalščini prešel na angleščino.

Avtomatizirajte kakovost prevodov

Z i18n-validate odkrijte manjkajoče ključe in poškodovane označbe mest, preden dosežejo uporabnike. Z i18n-pseudo preizkusite uporabniški vmesnik z lažnimi prevodi, preden prispejo pravi prevodi.

Odprtokodna orodja za i18n v Next.js

Ti odprtokodni paketi rešujejo pogoste težave v potekih dela internacionalizacije Next.js.

next-intl-localechain

Običajni next-intl se ob manjkajočem prevodu vrne neposredno k Vaši privzeti jezikovni različici. Uporabnik brazilske portugalščine namesto povsem ustreznih prevodov pt-PT vidi angleščino. next-intl-localechain doda pametne nadomestne verige: globoko združi prevode sorodnih jezikovnih različic, tako da regionalni uporabniki vedno vidijo najbližji razpoložljivi 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'
}));
Samodejno globoko združi prevode vzdolž verig jezikovnih različic
Vgrajene verige za portugalščino, španščino, francoščino, nemščino in druge jezike
Brez napak varno preskoči manjkajoče datoteke sporočil
Nastavitev v eni vrstici: ovije Vaš obstoječi getRequestConfig
Oglejte si na GitHubu

@i18n-agent/cli

Orodje ukazne vrstice za prevajanje datotek sporočil Next.js, ne da bi zapustili terminal. Prevajajte datoteke neposredno, preverjajte stanje opravil in prenašajte rezultate. Deluje v pipelineih CI/CD z overjanjem s ključem API za povsem avtomatizirane lokalizacijske poteke dela.

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
Iz terminala prevajajte JSON, YAML, PO in druge oblike datotek i18n
Pripravljeno za CI/CD: za samodejne pipeline uporabite overjanje z okoljsko spremenljivko
Spremljajte stanje opravil, nadaljujte neuspešna opravila in prenašajte rezultate
Strojno berljiv izhod JSON za skriptiranje in avtomatizacijo
Oglejte si na GitHubu

Pogoste pasti

"Unable to find next-intl locale"

Vmesna programska oprema se ni ujemala z zahtevo. Preverite: ali je middleware.ts v korenu projekta? Ali vzorec matcher pravilno izključuje statične datoteke? Ali je jezikovna različica vključena v Vaše nastavitve usmerjanja?

Nepričakovan dinamični izris

Na strani ali v postavitvi manjka setRequestLocale(locale). Brez tega next-intl za zaznavanje jezikovne različice uporablja glave in piškotke, kar vsili dinamični izris ter prepreči statično ustvarjanje.

Vzporedne poti ne delujejo z i18n

Vzporedne poti (@modal) in prestrezne poti ((.)photo) imajo znane nezdružljivosti z dinamičnim odsekom [locale]. Kot rešitev za te napredne vzorce usmerjanja uporabite usmerjanje na podlagi vmesne programske opreme.

Preklop jezika izgubi trenutno pot

Pri preklopu jezikovne različice z usePathname() ohranite trenutno pathname in zamenjajte samo jezikovni odsek. Bodite previdni pri dinamičnih parametrih poti: za novo jezikovno različico jih morate znova razrešiti.

Priporočena struktura datotek

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 tudi:

Preizkusite i18n Agent zdaj

Spustite prevajalsko datoteko sem

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

ali kliknite za izbiro

Ciljni jeziki

Registracija ni potrebnaTakojšnja ocena

Nadomestne jezikovne različice z next-intl-localechain

Ko v regionalni jezikovni različici, kot je pt-BR, manjka prevajalski ključ, next-intl preskoči naravnost na privzeto jezikovno različico, namesto da bi najprej preveril nadrejeno različico 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`),
});

V našem vodniku po nadomestnih jezikovnih različicah si oglejte celoten seznam podprtih ogrodij in 75 vgrajenih verig. Learn more →

Pogosta vprašanja