Skip to main content

Ang Kumpletong Gabay sa Next.js Internationalization

I-set up ang next-intl gamit ang App Router, i-configure ang locale routing, at i-automate ang pagsasalin gamit ang AI.

1

I-install ang next-intl

Ang next-intl ay iisang package na humahawak ng locale routing, message loading, at translation hook para sa Next.js App Router.

Terminal
npm install next-intl
Bakit next-intl kaysa next-i18next? Binubuo ang next-intl para sa App Router at server component. Idinisenyo ang next-i18next para sa Pages Router at limitado ang suporta nito sa App Router.
2

Gumawa ng i18n Request Config

Gumawa ng 2 file: src/i18n/request.ts para sa message loading at src/i18n/routing.ts para sa locale definition. Kino-configure ng mga ito kung paano nireresolba at niroroute ng next-intl ang mga message.

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);
Nangangailangan ang Turbopack (default bundler sa Next.js 15) ng experimental.turbo.resolveAlias sa inyong next.config.js. Kung wala ito, makakakuha kayo ng "Couldn't find next-intl config file" error.
3

I-configure ang Middleware

Magdagdag ng middleware.ts para pangasiwaan ang locale detection, URL rewriting, at redirect. Hinahadlangan ng middleware ang bawat request at tinitiyak na naa-apply ang tamang locale.

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|.*\\..*).*)'],
};
DAPAT nasa project root directory ang middleware.ts, hindi sa loob ng src/. Ito ang pinakakaraniwang configuration mistake sa next-intl.
4

I-set up ang Istruktura ng Folder na [locale]

Ilipat ang inyong mga app route sa loob ng app/[locale]/. Idagdag ang generateStaticParams para mag-generate ng mga page para sa bawat locale sa build time. Lumilikha ito ng istruktura ng URL na /en/about, /de/about, atbp.

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

export function generateStaticParams() {
  return routing.locales.map((locale) => ({ locale }));
}
DAPAT ninyong tawagin ang setRequestLocale(locale) sa bawat page.tsx at layout.tsx na gumagamit ng mga translation. Kapag wala ito, magfa-fallback ang Next.js sa dynamic rendering at malaki ang ibababa ng build performance.
5

I-update ang Root Layout

I-load ang mga message gamit ang getMessages() at ipasa ang mga ito sa NextIntlClientProvider sa inyong root locale layout. Itakda ang html lang attribute mula sa locale parameter.

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>
  );
}
Nangangailangan ang NextIntlClientProvider ng tahasang locale prop. Kapag inalis ito, nagdudulot ito ng mga hindi halatang error sa mga client component na mahirap i-debug.
6

Gamitin ang mga Translation sa mga Component

Gumagamit ang mga server component ng getTranslations (async, await). Gumagamit ang mga client component ng useTranslations (hook). Pumili batay sa kung saan nagre-render ang inyong component — pinananatiling wala sa JavaScript bundle ang mga translation kapag server component ang gamit.

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')} />;
}
Mas piliin ang mga server component para sa isinaling nilalaman. Pinananatili nilang wala ang mga translation string sa inyong client JavaScript bundle, kaya nababawasan ang load time para sa mga user.
7

Magdagdag ng SEO: Metadata at Hreflang

Gamitin ang generateMetadata para gumawa ng mga page title at description na partikular sa locale. Idagdag ang alternates.languages para sa mga hreflang tag para matuklasan ng mga search engine ang lahat ng bersyon ng wika ng bawat page.

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}`])
      ),
    },
  };
}
Sa Vercel, maaaring mag-generate ang mga build ng localhost bilang canonical URL kapag hindi naka-set ang metadataBase. Palaging itakda ang metadataBase sa inyong root layout sa inyong production domain.
8

I-handle ang mga Error at Not-Found Page

Kailangan ng espesyal na pag-handle ang error.tsx at not-found.tsx dahil maaari silang mag-render sa labas ng karaniwang locale layout. Nangangailangan ang root not-found.tsx ng sarili nitong i18n provider setup para maipakita ang mga localized na error message.

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>
  );
}
Nire-render lang ng Next.js ang inyong localized na 404 page kapag tahasang tinawag ang notFound() sa inyong code. Ang mga unknown route na walang katugmang page ay magpapakita ng default na Next.js 404, hindi ang inyong localized na bersyon.
9

I-automate ang mga Pagsasalin

Kapag kumpleto na ang inyong i18n setup, isalin ang inyong mga message file gamit ang AI nang direkta mula sa inyong IDE, o gamitin ang i18n Agent CLI sa inyong CI/CD pipeline para sa awtomatikong pagsasalin sa bawat deploy.

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)
Gamitin ang next-intl-localechain para sa intelligent locale fallback — makakakita ang pt-BR user ng mga pagsasalin sa pt-PT sa halip na mag-fallback sa English kapag hindi available ang Brazilian Portuguese.

I-automate ang Kalidad ng Pagsasalin

Mahuli ang mga nawawalang key at sirang placeholder bago ma-ship gamit ang i18n-validate. I-test ang inyong UI gamit ang mga pekeng pagsasalin sa pamamagitan ng i18n-pseudo bago dumating ang mga totoong pagsasalin.

Mga Open-Source Tool para sa Next.js i18n

Tinutugunan ng mga open-source package na ito ang mga karaniwang pain point sa mga workflow ng internationalization sa Next.js.

next-intl-localechain

Direktang nagfa-fallback ang standard next-intl sa inyong default locale kapag may nawawalang translation. Nakakakita ang isang Brazilian Portuguese user ng English sa halip na maayos na mga pagsasalin sa pt-PT. Nagdaragdag ang next-intl-localechain ng intelligent fallback chain — dini-deep-merge nito ang mga pagsasalin mula sa mga magkakaugnay na locale para laging makita ng mga user sa bawat rehiyon ang pinakamalapit na available na pagsasalin.

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'
}));
Awtomatikong dini-deep-merge ang mga pagsasalin sa buong locale chain
May built-in chain para sa Portuguese, Spanish, French, German, at iba pa
Maayos na nilalaktawan ang mga nawawalang message file nang walang error
One-line setup — bino-wrap ang inyong kasalukuyang getRequestConfig
Tingnan sa GitHub

@i18n-agent/cli

Isang command-line tool para isalin ang inyong mga Next.js message file nang hindi umaalis sa terminal. Isalin ang mga file nang direkta, suriin ang job status, at i-download ang mga resulta. Gumagana ito sa mga CI/CD pipeline gamit ang API key authentication para sa ganap na automated na localization workflow.

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
Isalin ang JSON, YAML, PO, at iba pang i18n file format mula sa terminal
CI/CD ready — mag-authenticate sa pamamagitan ng environment variable para sa mga automated pipeline
Subaybayan ang job status, i-resume ang mga nabigong job, at i-download ang mga resulta
Machine-readable na JSON output para sa scripting at automation
Tingnan sa GitHub

Mga Karaniwang Pitfall

"Unable to find next-intl locale"

Hindi tumugma ang middleware sa request. Suriin: nasa project root ba ang middleware.ts? Tama bang nag-e-exclude ng mga static file ang matcher pattern? Kasama ba ang locale sa inyong routing config?

Hindi Inaasahang Dynamic Rendering

Wala ang setRequestLocale(locale) sa isang page o layout. Kapag wala ito, gumagamit ang next-intl ng headers/cookies para i-detect ang locale, na nagpu-force ng dynamic rendering at pumipigil sa static generation.

Nasira ang Parallel Routes kapag may i18n

May mga kilalang incompatibility ang parallel routes (@modal) at intercepting routes ((.)photo) sa [locale] dynamic segment. Gamitin ang middleware-based routing bilang workaround para sa mga advanced routing pattern na ito.

Nawawala ang Kasalukuyang Route kapag Nagpapalit ng Wika

Kapag nagpapalit ng locale, panatilihin ang kasalukuyang pathname gamit ang usePathname() at palitan lang ang locale segment. Mag-ingat sa mga dynamic route parameter — kailangan silang i-resolve muli para sa bagong locale.

Inirerekomendang Istruktura ng File

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

Magsalin din ng:

Subukan ang i18n Agent Ngayon

I-drop dito ang inyong translation file

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

o i-click para mag-browse

Mga target language

Hindi kailangan ang signupInstant na estimate

Locale Fallback gamit ang next-intl-localechain

Kapag nawawala ang translation key sa isang regional locale tulad ng pt-BR, dumidiretso ang next-intl sa default locale sa halip na suriin muna ang parent locale na 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`),
});

Tingnan ang aming Locale Fallback Guide para sa kumpletong listahan ng mga sinusuportahang framework at 75 built-in chain. Learn more →

Mga Madalas Itanong