Skip to main content

Pilnīgs Next.js internacionalizācijas ceļvedis

Iestatiet next-intl ar App Router, konfigurējiet lokalizāciju maršrutēšanu un automatizējiet tulkošanu ar MI.

1

Instalēt next-intl

next-intl ir viena pakotne, kas apstrādā Next.js App Router lokalizāciju maršrutēšanu, ziņojumu ielādi un tulkošanas āķus.

Terminal
npm install next-intl
Kādēļ next-intl, nevis next-i18next? next-intl ir veidots App Router un servera komponentiem. next-i18next tika radīts Pages Router un App Router atbalsta ierobežoti.
2

Izveidot i18n pieprasījuma konfigurāciju

Izveidojiet divus failus: src/i18n/request.ts ziņojumu ielādei un src/i18n/routing.ts lokalizāciju definīcijām. Tie konfigurē, kā next-intl atrisina ziņojumus un maršrutus.

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 (Next.js 15 noklusējuma komplektētājs) failā next.config.js vajadzīgs experimental.turbo.resolveAlias. Bez tā saņemsiet kļūdas „Couldn't find next-intl config file“.
3

Konfigurēt starpprogrammatūru

Pievienojiet middleware.ts lokalizācijas noteikšanai, URL pārrakstīšanai un novirzīšanai. Starpprogrammatūra pārtver katru pieprasījumu un nodrošina pareizās lokalizācijas lietošanu.

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 OBLIGĀTI jāatrodas projekta saknes direktorijā, nevis src/. Tā ir visbiežākā next-intl konfigurācijas kļūda.
4

Izveidot [locale] mapju struktūru

Pārvietojiet lietotnes maršrutus uz app/[locale]/. Pievienojiet generateStaticParams, lai būvēšanas laikā ģenerētu lapas katrai lokalizācijai. Tas izveido URL struktūru /en/about, /de/about utt.

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

export function generateStaticParams() {
  return routing.locales.map((locale) => ({ locale }));
}
Katrā page.tsx un layout.tsx, kas izmanto tulkojumus, OBLIGĀTI jāizsauc setRequestLocale(locale). Bez tā Next.js atkāpjas uz dinamisku atveidi un būvējuma veiktspēja ievērojami pasliktinās.
5

Atjaunināt saknes izkārtojumu

Ielādējiet ziņojumus ar getMessages() un nododiet tos NextIntlClientProvider saknes lokalizācijas izkārtojumā. Iestatiet html atribūtu lang no lokalizācijas parametra.

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 vajadzīgs skaidri norādīts rekvizīts locale. To izlaižot, klienta komponentos rodas grūti atkļūdojamas, smalkas kļūdas.
6

Izmantot tulkojumus komponentos

Servera komponenti izmanto getTranslations (asinhroni, ar await), bet klienta komponenti — useTranslations (āķi). Izvēlieties atbilstoši komponenta atveides vietai: servera komponenti tulkojumus vispār neiekļauj JavaScript komplektā.

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')} />;
}
Tulkotam saturam izvēlieties servera komponentus. Tie neiekļauj tulkojumu virknes klienta JavaScript komplektā un samazina lietotāju ielādes laiku.
7

Pievienot SEO: metadatus un hreflang

Izmantojiet generateMetadata lokalizācijai specifisku lapu nosaukumu un aprakstu izveidei. Pievienojiet alternates.languages hreflang tagiem, lai meklētājprogrammas atrastu katras lapas versijas visās valodās.

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}`])
      ),
    },
  };
}
Ja metadataBase nav iestatīts, Vercel būvējumi var ģenerēt localhost kā kanonisko URL. Saknes izkārtojumā vienmēr iestatiet metadataBase uz produkcijas domēnu.
8

Apstrādāt kļūdu un neatrastu lapu skatus

error.tsx un not-found.tsx vajadzīga īpaša apstrāde, jo tie var tikt atveidoti ārpus parastā lokalizācijas izkārtojuma. Saknes not-found.tsx vajadzīgs savs i18n nodrošinātāja iestatījums, lai rādītu lokalizētus kļūdu ziņojumus.

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 atveido jūsu lokalizēto 404 lapu tikai tad, ja kodā skaidri izsaukts notFound(). Nezināmi maršruti bez atbilstošas lapas rāda noklusējuma Next.js 404, nevis jūsu lokalizēto versiju.
9

Automatizēt tulkošanu

Kad i18n iestatīšana ir pabeigta, tulkojiet ziņojumu failus ar MI tieši no IDE vai izmantojiet i18n Agent CLI CI/CD konveijerā automatizētai tulkošanai katrā izvietošanā.

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)
Viedām lokalizāciju atkāpšanās ķēdēm izmantojiet next-intl-localechain: ja Brazīlijas portugāļu valoda nav pieejama, pt-BR lietotājs redzēs pt-PT tulkojumus, nevis atkāpsies uz angļu valodu.

Automatizēt tulkojumu kvalitāti

Ar i18n-validate pirms izlaišanas atrodiet trūkstošās atslēgas un bojātos vietturus. Kamēr īstie tulkojumi vēl nav gatavi, pārbaudiet UI ar i18n-pseudo pseidotulkojumiem.

Atvērtā pirmkoda rīki Next.js i18n

Šīs atvērtā pirmkoda pakotnes risina biežas Next.js internacionalizācijas darbplūsmu problēmas.

next-intl-localechain

Ja trūkst tulkojuma, standarta next-intl uzreiz atkāpjas uz noklusējuma lokalizāciju. Brazīlijas portugāļu valodas lietotājs labu pt-PT tulkojumu vietā redz angļu valodu. next-intl-localechain pievieno viedas atkāpšanās ķēdes: tas dziļi sapludina saistītu lokalizāciju tulkojumus, lai reģionālie lietotāji vienmēr redzētu tuvāko pieejamo tulkojumu.

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'
}));
Automātiski dziļi sapludina tulkojumus lokalizāciju ķēdēs
Iebūvētas ķēdes portugāļu, spāņu, franču, vācu un citām valodām
Nemanāmi un bez kļūdām izlaiž trūkstošos ziņojumu failus
Vienas rindas iestatīšana — aptver esošo getRequestConfig
Skatīt GitHub

@i18n-agent/cli

Komandrindas rīks Next.js ziņojumu failu tulkošanai, neizejot no termināļa. Tulkojiet failus tieši, pārbaudiet uzdevumu stāvokli un lejupielādējiet rezultātus. Darbojas CI/CD konveijeros ar API atslēgas autentifikāciju un nodrošina pilnībā automatizētas lokalizācijas darbplūsmas.

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
Tulkojiet JSON, YAML, PO un citus i18n failu formātus no termināļa
Gatavs CI/CD: automatizētos konveijeros autentificējieties ar vides mainīgo
Izsekojiet uzdevuma stāvokli, atsāciet neizdevušos uzdevumus un lejupielādējiet rezultātus
Mašīnlasāma JSON izvade skriptēšanai un automatizācijai
Skatīt GitHub

Biežākās kļūdas

„Unable to find next-intl locale“

Starpprogrammatūra neatbilda pieprasījumam. Pārbaudiet: vai middleware.ts atrodas projekta saknē? Vai matcher modelis pareizi izslēdz statiskos failus? Vai lokalizācija ir iekļauta maršrutēšanas konfigurācijā?

Negaidīta dinamiska atveide

Lapā vai izkārtojumā trūkst setRequestLocale(locale). Bez tā next-intl lokalizācijas noteikšanai izmanto galvenes un sīkfailus, kas piespiež dinamisku atveidi un neļauj veikt statisku ģenerēšanu.

Paralēlie maršruti nedarbojas ar i18n

Paralēliem (@modal) un pārtverošiem ((.)photo) maršrutiem ir zināmas nesaderības ar dinamisko segmentu [locale]. Šiem paplašinātajiem maršrutēšanas modeļiem kā apiešanas risinājumu izmantojiet uz starpprogrammatūru balstītu maršrutēšanu.

Mainot valodu, tiek zaudēts pašreizējais maršruts

Mainot lokalizācijas, saglabājiet pašreizējo ceļa nosaukumu ar usePathname() un aizstājiet tikai lokalizācijas segmentu. Uzmanieties ar dinamiskiem maršruta parametriem — tie jaunajai lokalizācijai jāatrisina no jauna.

Ieteicamā failu struktūra

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

Tulkojiet arī:

Izmēģiniet i18n Agent tūlīt

Nometiet tulkošanas failu šeit

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

vai noklikšķiniet, lai izvēlētos

Mērķa valodas

Reģistrācija nav vajadzīgaTūlītēja tāme

Lokalizācijas atkāpšanās ar next-intl-localechain

Ja reģionālajā lokalizācijā, piemēram, pt-BR, trūkst tulkojuma atslēgas, next-intl uzreiz pāriet uz noklusējuma lokalizāciju, nevis vispirms pārbauda vecāklokalizāciju 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`),
});

Pilnu atbalstīto sistēmu sarakstu un 75 iebūvētās ķēdes skatiet mūsu lokalizāciju atkāpšanās ceļvedī. Learn more →

Bieži uzdotie jautājumi