
Next.js uluslararasılaştırma için eksiksiz rehber
App Router ile next-intl'ı kurun, yerel ayar yönlendirmesini yapılandırın ve çevirileri yapay zeka ile otomatikleştirin.
next-intl'ı yükleyin
next-intl, Next.js App Router için yerel ayar yönlendirmesini, ileti yüklemeyi ve çeviri kancalarını yöneten tek bir pakettir.
npm install next-intli18n istek yapılandırmasını oluşturun
İki dosya oluşturun: ileti yüklemek için src/i18n/request.ts ve yerel ayarları tanımlamak için src/i18n/routing.ts. Bu dosyalar, next-intl'ın iletileri ve rotaları nasıl çözümleyeceğini yapılandırır.
// 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);Ara yazılımı yapılandırın
Yerel ayar algılama, URL'leri yeniden yazma ve yönlendirme işlemleri için middleware.ts dosyasını ekleyin. Ara yazılım her isteği yakalar ve doğru yerel ayarın uygulanmasını sağlar.
// 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|.*\\..*).*)'],
};[locale] klasör yapısını kurun
Uygulama rotalarınızı app/[locale]/ içine taşıyın. Derleme sırasında her yerel ayar için sayfalar oluşturmak üzere generateStaticParams ekleyin. Böylece /en/about, /de/about vb. URL yapısı oluşturulur.
// app/[locale]/layout.tsx
import { routing } from '@/i18n/routing';
export function generateStaticParams() {
return routing.locales.map((locale) => ({ locale }));
}Kök düzeninizi güncelleyin
İletileri getMessages() ile yükleyin ve kök yerel ayar düzeninizde NextIntlClientProvider'a iletin. html lang özniteliğini yerel ayar parametresinden ayarlayın.
// 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>
);
}Bileşenlerde çevirileri kullanın
Sunucu bileşenleri getTranslations (asenkron, await), istemci bileşenleri ise useTranslations (kanca) kullanır. Bileşeninizin nerede işlendiğine göre seçim yapın. Sunucu bileşenleri çevirileri JavaScript paketinin tamamen dışında tutar.
// 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')} />;
}SEO ekleyin: Meta veriler ve hreflang
Yerel ayara özgü sayfa başlıkları ve açıklamalar oluşturmak için generateMetadata kullanın. Arama motorlarının her sayfanın tüm dil sürümlerini keşfedebilmesi için hreflang etiketlerine alternates.languages ekleyin.
// 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}`])
),
},
};
}Hata ve bulunamadı sayfalarını yönetin
error.tsx ve not-found.tsx normal yerel ayar düzeninin dışında işlenebildiği için özel işlem gerektirir. Kök not-found.tsx, yerelleştirilmiş hata iletilerini göstermek üzere kendi i18n sağlayıcı kurulumuna ihtiyaç duyar.
// 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>
);
}Çevirileri otomatikleştirin
i18n kurulumunuz tamamlandığında ileti dosyalarınızı doğrudan IDE'nizden yapay zeka ile çevirin veya her dağıtımda otomatik çeviri için CI/CD işlem hattınızda i18n Agent CLI'ı kullanın.
# 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)Çeviri kalitesini otomatikleştirin
Next.js i18n için açık kaynak araçlar
Bu açık kaynak paketler, Next.js uluslararasılaştırma iş akışlarındaki yaygın sorunları çözer.
next-intl-localechain
Standart next-intl, bir çeviri eksik olduğunda doğrudan varsayılan yerel ayarınıza döner. Brezilya Portekizcesi kullanan biri, uygun pt-PT çevirileri mevcut olsa bile İngilizceyi görür. next-intl-localechain akıllı geri dönüş zincirleri ekler ve ilişkili yerel ayarlardaki çevirileri derinlemesine birleştirerek bölgesel kullanıcıların daima mevcut en yakın çeviriyi görmesini sağlar.
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'
}));@i18n-agent/cli
Terminalden ayrılmadan Next.js ileti dosyalarınızı çevirmek için bir komut satırı aracıdır. Dosyaları doğrudan çevirin, iş durumunu kontrol edin ve sonuçları indirin. Tamamen otomatik yerelleştirme iş akışları için API anahtarıyla kimlik doğrulayarak CI/CD işlem hatlarında çalışır.
# 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,esYaygın sorunlar
"Unable to find next-intl locale"
Ara yazılım istekle eşleşmedi. Şunları kontrol edin: middleware.ts proje kökünde mi? Eşleştirici deseni statik dosyaları doğru biçimde hariç tutuyor mu? Yerel ayar yönlendirme yapılandırmanıza eklenmiş mi?
Beklenmeyen dinamik işleme
Bir sayfa veya düzende setRequestLocale(locale) eksik. Bu işlev olmadan next-intl yerel ayarı algılamak için üst bilgileri/çerezleri kullanır; bu da dinamik işlemeyi zorunlu kılar ve statik oluşturmayı engeller.
Paralel rotalar i18n ile çalışmıyor
Paralel rotaların (@modal) ve yakalayıcı rotaların ((.)photo), [locale] dinamik segmentiyle bilinen uyumsuzlukları vardır. Bu gelişmiş yönlendirme desenleri için geçici çözüm olarak ara yazılım tabanlı yönlendirme kullanın.
Dil değiştirildiğinde geçerli rota kayboluyor
Yerel ayarlar arasında geçiş yaparken usePathname() kullanarak geçerli yol adını koruyun ve yalnızca yerel ayar segmentini değiştirin. Dinamik rota parametrelerine dikkat edin; yeni yerel ayar için yeniden çözümlenmeleri gerekir.
Önerilen dosya yapısı
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.jsoni18n Agent'ı şimdi deneyin
Çeviri dosyanızı buraya bırakın
JSON, YAML, PO, XML, CSV, Markdown, Properties
veya göz atmak için tıklayın
Hedef diller
next-intl-localechain ile yerel ayar geri dönüşü
pt-BR gibi bölgesel bir yerel ayarda çeviri anahtarı eksik olduğunda next-intl önce üst yerel ayar pt'yi kontrol etmek yerine doğrudan varsayılan yerel ayara geçer.
npm install next-intl-localechainimport { 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`),
});Desteklenen çerçevelerin ve 75 yerleşik zincirin tam listesi için Yerel Ayar Geri Dönüş Rehberimize bakın. Learn more →