Skip to main content

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.

1

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.

Terminal
npm install next-intl
Neden next-i18next yerine next-intl? next-intl, App Router ve sunucu bileşenleri için geliştirilmiştir. next-i18next ise Pages Router için tasarlanmıştır ve App Router desteği sınırlıdır.
2

i18n 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
// 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'in varsayılan paketleyicisi), next.config.js dosyanızda experimental.turbo.resolveAlias bulunmasını gerektirir. Bu ayar olmadan "Couldn't find next-intl config file" hataları alırsınız.
3

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
// 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, src/ içinde değil projenizin kök dizininde OLMALIDIR. Bu, next-intl ile ilgili en yaygın yapılandırma hatasıdır.
4

[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
// app/[locale]/layout.tsx
import { routing } from '@/i18n/routing';

export function generateStaticParams() {
  return routing.locales.map((locale) => ({ locale }));
}
Çeviri kullanan her page.tsx ve layout.tsx dosyasında setRequestLocale(locale) işlevini çağırmanız GEREKİR. Aksi takdirde Next.js dinamik işlemeye geri döner ve derleme performansınız önemli ölçüde düşer.
5

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
// 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 açık bir locale özelliği gerektirir. Bu özelliğin belirtilmemesi, istemci bileşenlerinde ayıklanması zor ve fark edilmesi güç hatalara neden olur.
6

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.

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')} />;
}
Çevrilmiş içerik için sunucu bileşenlerini tercih edin. Bu bileşenler çeviri dizelerini istemci JavaScript paketinizin dışında tutarak kullanıcıların yükleme süresini kısaltır.
7

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
// 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}`])
      ),
    },
  };
}
metadataBase ayarlanmazsa Vercel'deki derlemeler standart URL olarak localhost oluşturabilir. Kök düzeninizde metadataBase değerini daima üretim alan adınız olarak ayarlayın.
8

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
// 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, yerelleştirilmiş 404 sayfanızı yalnızca kodunuzda notFound() açıkça çağrıldığında işler. Eşleşen sayfası olmayan bilinmeyen rotalar, yerelleştirilmiş sürümünüz yerine varsayılan Next.js 404 sayfasını gösterir.
9

Ç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.

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)
Akıllı yerel ayar geri dönüşleri için next-intl-localechain kullanın. Böylece pt-BR kullanan biri, Brezilya Portekizcesi mevcut olmadığında İngilizceye dönmek yerine pt-PT çevirilerini görür.

Çeviri kalitesini otomatikleştirin

Eksik anahtarları ve bozuk yer tutucuları yayımlanmadan önce i18n-validate ile yakalayın. Gerçek çeviriler gelmeden önce i18n-pseudo ile sahte çeviriler kullanarak arayüzünüzü test edin.

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.

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'
}));
Yerel ayar zincirlerindeki çevirileri otomatik olarak derinlemesine birleştirir
Portekizce, İspanyolca, Fransızca, Almanca ve daha fazlası için yerleşik zincirler
Eksik ileti dosyalarını hata vermeden atlar
Tek satırlık kurulumla mevcut getRequestConfig işlevinizi sarmalar
GitHub'da görüntüleyin

@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.

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
JSON, YAML, PO ve diğer i18n dosya biçimlerini terminalden çevirir
CI/CD için hazırdır; otomatik işlem hatlarında ortam değişkeniyle kimlik doğrular
İş durumunu izler, başarısız işleri sürdürür ve sonuçları indirir
Betik yazma ve otomasyon için makine tarafından okunabilir JSON çıktısı
GitHub'da görüntüleyin

Yaygı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ı

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

i18n 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

Kayıt gerekmezAnında fiyat tahmini

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.

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`),
});

Desteklenen çerçevelerin ve 75 yerleşik zincirin tam listesi için Yerel Ayar Geri Dönüş Rehberimize bakın. Learn more →

Sık sorulan sorular