Skip to main content

Fullnaðarleiðarvísir um alþjóðavæðingu Next.js

Settu next-intl upp með App Router, grunnstilltu tungumálaleiðaval og gerðu þýðingar sjálfvirkar með gervigreind.

1

Settu next-intl upp

next-intl er einn pakki sem sér um tungumálaleiðaval, hleðslu skilaboða og þýðingarkróka fyrir Next.js App Router.

Terminal
npm install next-intl
Hvers vegna next-intl frekar en next-i18next? next-intl er smíðað fyrir App Router og miðlarahluta. next-i18next var hannað fyrir Pages Router og styður App Router aðeins að takmörkuðu leyti.
2

Búðu til i18n-beiðnastillinguna

Búðu til tvær skrár: src/i18n/request.ts fyrir hleðslu skilaboða og src/i18n/routing.ts fyrir skilgreiningar tungumálasniða. Þær ákvarða hvernig next-intl finnur skilaboð og leiðir.

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 (sjálfgefið pökkunartól í Next.js 15) krefst experimental.turbo.resolveAlias í next.config.js. Án þess færðu villuboðin "Couldn't find next-intl config file".
3

Grunnstilltu millibúnað

Bættu middleware.ts við til að annast greiningu tungumálasniðs, endurritun vefslóða og áframsendingar. Millibúnaðurinn grípur hverja beiðni og tryggir að réttu tungumálasniði sé beitt.

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 VERÐUR að vera í rótarmöppu verkefnisins, ekki inni í src/. Þetta eru langalgengustu grunnstillingarmistökin við notkun next-intl.
4

Settu upp [locale]-möppuskipanina

Færðu forritsleiðirnar inn í app/[locale]/. Bættu generateStaticParams við til að búa til síður fyrir hvert tungumálasnið við smíði. Þannig verður vefslóðaskipanin /en/about, /de/about o.s.frv.

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

export function generateStaticParams() {
  return routing.locales.map((locale) => ({ locale }));
}
Þú VERÐUR að kalla á setRequestLocale(locale) í hverri page.tsx og layout.tsx sem notar þýðingar. Án þess fellur Next.js aftur á kvika myndgerð og afköst smíðinnar versna verulega.
5

Uppfærðu rótarsíðuskipulagið

Hladdu skilaboðum með getMessages() og sendu þau til NextIntlClientProvider í rótarsíðuskipulagi tungumálasniðsins. Stilltu lang-eigindi html út frá færibreytu tungumálasniðsins.

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 krefst þess að locale-eigindið sé tilgreint sérstaklega. Ef því er sleppt valda það lúmskum villum í biðlarahlutum sem erfitt er að kemba.
6

Notaðu þýðingar í hlutum

Miðlarahlutar nota getTranslations (ósamstillt, await). Biðlarahlutar nota useTranslations (krók). Veldu eftir því hvar hluturinn er myndgerður — miðlarahlutar halda þýðingum alfarið utan JavaScript-pakkans.

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')} />;
}
Veldu miðlarahluta fyrir þýtt efni. Þeir halda þýðingarstrengjum utan JavaScript-biðlarapakkans og stytta hleðslutíma notenda.
7

Bættu við leitarvélabestun: lýsigögnum og hreflang

Notaðu generateMetadata til að búa til tungumálasértæka síðutitla og lýsingar. Bættu alternates.languages við fyrir hreflang-merki svo leitarvélar finni allar tungumálaútgáfur hverrar síðu.

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 geta smíðir myndað localhost sem viðurkennda vefslóð ef metadataBase er ekki stillt. Stilltu metadataBase á rekstrarlénið þitt í rótarsíðuskipulaginu.
8

Meðhöndlaðu villu- og síður-finnast-ekki-síður

error.tsx og not-found.tsx þarfnast sérstakrar meðhöndlunar því þær geta verið myndgerðar utan venjulega tungumálasíðuskipulagsins. not-found.tsx í rótinni þarf eigin uppsetningu i18n-veitu til að birta staðfærð villuboð.

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 myndgerir aðeins staðfærðu 404-síðuna þína þegar sérstaklega er kallað á notFound() í kóðanum. Óþekktar leiðir án samsvarandi síðu sýna sjálfgefnu 404-síðu Next.js, ekki staðfærðu útgáfuna þína.
9

Gerðu þýðingar sjálfvirkar

Þegar i18n-uppsetningunni er lokið geturðu þýtt skilaboðaskrárnar með gervigreind beint úr þróunarumhverfinu eða notað skipanalínuviðmót i18n Agent í CI/CD-vinnslurásinni til að þýða sjálfvirkt við hverja útgáfu.

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)
Notaðu next-intl-localechain fyrir snjallt varatungumálaval — notandi með pt-BR sér pt-PT-þýðingar í stað þess að kerfið falli aftur á ensku þegar brasilísk portúgalska er ekki tiltæk.

Gerðu þýðingargæði sjálfvirk

Finndu lykla sem vantar og skemmd staðgengilsgildi áður en þau fara í útgáfu með i18n-validate. Prófaðu notandaviðmótið með gerviþýðingum með i18n-pseudo áður en raunverulegar þýðingar berast.

Opinn hugbúnaður fyrir i18n í Next.js

Þessir opnu hugbúnaðarpakkar leysa algenga erfiðleika í verkferlum við alþjóðavæðingu Next.js.

next-intl-localechain

Venjulegt next-intl fellur beint aftur á sjálfgefna tungumálasniðið þegar þýðingu vantar. Notandi brasilískrar portúgölsku sér ensku í stað fullgóðra pt-PT-þýðinga. next-intl-localechain bætir við snjöllum varatungumálakeðjum — það djúpsameinar þýðingar úr skyldum tungumálasniðum svo notendur svæðisbundinna sniða sjái ávallt nærtækustu tiltæku þýðinguna.

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'
}));
Djúpsameinar þýðingar sjálfvirkt milli tungumálasniðskeðja
Innbyggðar keðjur fyrir portúgölsku, spænsku, frönsku, þýsku og fleiri tungumál
Sleppir skilaboðaskrám sem vantar hnökralaust og án villna
Uppsetning í einni línu — umlykur núverandi getRequestConfig
Skoða á GitHub

@i18n-agent/cli

Skipanalínutól til að þýða Next.js-skilaboðaskrárnar þínar án þess að yfirgefa stjórnskjáinn. Þýddu skrár beint, athugaðu stöðu verka og sæktu niðurstöður. Virkar í CI/CD-vinnslurásum með auðkenningu með API-lykli fyrir alsjálfvirka staðfæringarverkferla.

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
Þýddu JSON-, YAML-, PO- og önnur i18n-skráasnið úr stjórnskjánum
Tilbúið fyrir CI/CD — auðkenndu með umhverfisbreytu fyrir sjálfvirkar vinnslurásir
Fylgstu með stöðu verka, haltu misheppnuðum verkum áfram og sæktu niðurstöður
Véllesanlegt JSON-úttak fyrir skriftur og sjálfvirkni
Skoða á GitHub

Algengar gryfjur

"Unable to find next-intl locale"

Millibúnaðurinn samsvaraði ekki beiðninni. Athugaðu: er middleware.ts í rót verkefnisins? Útilokar samsvörunarmynstrið óbreytanlegar skrár rétt? Er tungumálasniðið tilgreint í leiðavalsstillingunni?

Óvænt kvik myndgerð

setRequestLocale(locale) vantar á síðu eða í síðuskipulag. Án þess notar next-intl hausa/vafrakökur til að greina tungumálasniðið, sem þvingar fram kvika myndgerð og kemur í veg fyrir fasta myndun.

Samhliða leiðir bila með i18n

Samhliða leiðir (@modal) og leiðir sem grípa inn í ((.)photo) eru þekktar fyrir ósamhæfi við kvika [locale]-leiðarhlutann. Notaðu leiðaval byggt á millibúnaði sem hjáleið fyrir þessi þróuðu leiðavalsmynstur.

Við tungumálaskipti glatast núverandi leið

Þegar skipt er um tungumálasnið skaltu varðveita núverandi slóðarheiti með usePathname() og aðeins skipta út tungumálahlutanum. Gættu þín á kvikum leiðarfæribreytum — leysa þarf þær aftur fyrir nýja tungumálasniðið.

Ráðlögð skráaskipan

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

Prófaðu i18n Agent núna

Slepptu þýðingarskránni þinni hér

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

eða smelltu til að fletta

Markmál

Engin skráning nauðsynlegKostnaðaráætlun samstundis

Varatungumálaval með next-intl-localechain

Þegar þýðingarlykil vantar í svæðisbundið tungumálasnið á borð við pt-BR stekkur next-intl beint í sjálfgefna tungumálasniðið í stað þess að athuga fyrst yfirtungumálasniðið 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`),
});

Sjá leiðarvísi okkar um varatungumálaval fyrir heildarlista yfir studda hugbúnaðarramma og 75 innbyggðar keðjur. Learn more →

Algengar spurningar