Mevcut bir Next.js uygulamasını çok dilli (i18n) hale getirme (i18n kılavuzu 2026)

GitHub'daki Uygulama Şablonunu inceleyin.

İçindekiler

Mevcut bir uygulamayı uluslararasılaştırmak neden zordur?

Eğer daha önce sadece tek bir dil için oluşturulmuş bir uygulamaya birden fazla dil eklemeye çalıştıysanız, bunun ne kadar zor olduğunu bilirsiniz. Bu sadece "zor" değil, aynı zamanda sıkıcıdır. Her dosyayı incelemeli, her metin dizesini bulmalı ve bunları ayrı sözlük dosyalarına taşımalısınız.

Ardından asıl riskli kısım gelir: Tasarımı veya iş mantığını bozmadan tüm bu metinleri kod kancalarıyla değiştirmek. Bu, yeni özelliklerin geliştirilmesini haftalarca durduran ve bitmek bilmeyen bir refaktöring hissi veren bir iştir.

Intlayer Derleyicisi Nedir?

Intlayer Derleyicisi, bu manuel işleri atlamanız için yaratıldı. Metin dizelerini manuel olarak çıkarmak yerine, derleyici bunu sizin yerinize yapar. Kodunuzu tarar, metinleri bulur ve arka planda sözlükleri oluşturmak için AI kullanır. Daha sonra, derleme adımı sırasında gerekli i18n hook'larını yerleştirmek için kaynak kodunuzu değiştirir. Temel olarak uygulamanızı tek bir dildeymiş gibi yazmaya devam edersiniz ve derleyici çok dilli dönüştürme işlemini otomatik olarak yönetir.

Derleyici belgeleri: /tr/doc/compiler

Sınırlamalar

Derleyici kod analizini ve dönüşümünü (hook yerleştirme ve sözlük oluşturma) derleme anında gerçekleştirdiği için uygulamanızın derleme süresini yavaşlatabilir.

Aktif geliştirme sırasında (dev modu) bu etkiyi sınırlamak için derleyiciyi 'build-only' moduna ayarlayabilir veya ihtiyaç duymadığınızda devre dışı bırakabilirsiniz.

Next.js uygulamasında Intlayer Kurulumu için Adım Adım Kılavuz

Adım 1: Bağımlılıkları Yükleyin

Tercih ettiğiniz paket yöneticisini kullanarak gerekli paketleri yükleyin:

npm install intlayer next-intlayernpm install @intlayer/babel --save-devnpx intlayer init

• intlayer

  Yapılandırma yönetimi, çeviri, içerik tanımlama, derleme ve CLI komutları için uluslararasılaştırma araçlarını sağlayan temel pakettir.

• next-intlayer

  Intlayer'ı Next.js ile entegre eden pakettir. Next.js uluslararasılaştırması için bağlam sağlayıcıları ve hook'lar sunar. Ayrıca Intlayer'ı Webpack veya Turbopack ile entegre etmek için Next.js eklentisinin yanı sıra kullanıcının tercih ettiği dili algılamak, çerezleri yönetmek ve URL yönlendirmelerini idare etmek için ara yazılım (middleware) içerir.

Adım 2: Projenizi Yapılandırın

Uygulamanızın dillerini tanımlamak için bir yapılandırma dosyası oluşturun:

import { Locales, type IntlayerConfig } from "intlayer";const config: IntlayerConfig = {  internationalization: {    locales: [Locales.ENGLISH, Locales.TURKISH],    defaultLocale: Locales.TURKISH,  },  routing: {    mode: "search-params",  },  compiler: {    /**     * Derleyicinin etkinleştirilip etkinleştirilmeyeceğini belirtir.     */    enabled: true,    /**     * Optimize edilmiş sözlükler für çıktı dizini.     */    output: ({ locale, key }) => `compiler/${locale}/${key}.json`,    /**     * Oluşturulan dosyaya yalnızca içeriği yerleştirin, anahtar olmadan.     */    noMetadata: false,    /**     * Sözlük anahtar öneki     */    dictionaryKeyPrefix: "", // Remove base prefix    /**     * Bileşenlerin dönüştürüldükten sonra kaydedilip kaydedilmeyeceğini belirtir.     * Bu şekilde, derleyici uygulamayı dönüştürmek için yalnızca bir kez çalıştırılabilir ve ardından kaldırılabilir.     */    saveComponents: false,  },  ai: {    provider: "openai",    model: "gpt-5-mini",    apiKey: process.env.OPEN_AI_API_KEY,    applicationContext: "Bu basit bir harita uygulaması örneğidir",  },};export default config;

Not: OPEN_AI_API_KEY'nin çevresel değişkenleriniz içinde yapılandırıldığından emin olun.

Bu yapılandırma dosyası ile yerelleştirilmiş URL'leri, vekil yönlendirmelerini, çerez eşlemelerini, içerik dosyalarınızın konumu ve uzantısını ayarlayabilir, konsoldaki Intlayer günlüklerini devre dışı bırakabilir ve daha fazlasını yapabilirsiniz. Kullanılabilir parametrelerin tam listesi için yapılandırma belgelerine göz atın.

Adım 3: Intlayer'ı Next.js Yapılandırmanıza Entegre Edin

Next.js kurulumunuzu Intlayer kullanacak şekilde yapılandırın:

import type { NextConfig } from "next";import { withIntlayer } from "next-intlayer/server";const nextConfig: NextConfig = {  /* Buraya isteğe bağlı ek Next.js yapılandırması */};export default withIntlayer(nextConfig);

withIntlayer() Next.js eklentisi, Intlayer'ı Next.js ile entegre etmek için kullanılır. Sözlük dosyalarının oluşturulmasını sağlar ve dev modunda onları izler. Intlayer ortam değişkenlerini Webpack veya Turbopack ortamları içinde tanımlar. Dahası, performansı optimize etmek için takma adlar sağlar ve Sunucu Bileşenleriyle tam uyumlu çalışır.

Babel'i Yapılandır

Intlayer derleyicisi, içeriğinizi çıkarmak ve optimize etmek için Babel gerektirir. Intlayer eklentilerini içerecek şekilde babel.config.js (veya babel.config.json) dosyanızı güncelleyin:

const {  intlayerExtractBabelPlugin,  intlayerOptimizeBabelPlugin,  getExtractPluginOptions,  getOptimizePluginOptions,} = require("@intlayer/babel");module.exports = {  presets: ["next/babel"],  plugins: [    [intlayerExtractBabelPlugin, getExtractPluginOptions()],    [intlayerOptimizeBabelPlugin, getOptimizePluginOptions()],  ],};

Adım 4: Sayfanızda Dil Algılama

RootLayout bileşeninizin içeriğini temizleyin ve aşağıdaki örnekle değiştirin:

import type { Metadata } from "next";import type { ReactNode } from "react";import "./globals.css";import { IntlayerClientProvider, LocalPromiseParams } from "next-intlayer";import { getHTMLTextDir, getIntlayer } from "intlayer";import { getLocale } from "next-intlayer/server";export { generateStaticParams } from "next-intlayer";export const generateMetadata = async (): Promise<Metadata> => {  const locale = await getLocale();  const { title, description, keywords } = getIntlayer("metadata", locale);  return {    title,    description,    keywords,  };};const RootLayout = async ({  children,}: Readonly<{  children: ReactNode;}>) => {  const locale = await getLocale();  return (    <html lang={locale} dir={getHTMLTextDir(locale)}>      <IntlayerClientProvider defaultLocale={locale}>        <body>{children}</body>      </IntlayerClientProvider>    </html>  );};export default RootLayout;

Adım 5: İçeriğinizi Tanımlayın (Otomatik)

Derleyici etkinken artık içerik sözlüklerini (örn. .content.ts dosyaları) manuel olarak tanımlamanıza gerek kalmaz.

Bunun yerine, içeriğinizi kodunuza doğrudan sabit dizeler (hardcoded strings) olarak yazarsınız. Intlayer kaynak kodu tarar, yapılandırılmış AI sağlayıcısını kullanarak çeviriler oluşturur ve derleme aşamasında bu dizeleri yerelleştirilmiş içerikle sessizce değiştirir. Bunların hepsi tamamen otomatiktir.

Bileşeninize varsayılan dilinizde sabit dizeler yazın ve gerisini Intlayer Derleyicisi'ne bırakın.

page.tsx dosyanızın nasıl görüneceğine dair örnek:

import type { FC } from "react";import { IntlayerServerProvider } from "next-intlayer/server";import { getLocale } from "next-intlayer/server";const PageContent: FC = () => {return (  <>    <p>Bunu düzenleyerek başlayın!</p>    <code>src/app/page.tsx</code>  </>);};export default async function Page() {const locale = await getLocale();return (  <IntlayerServerProvider locale={locale}>    <PageContent />  </IntlayerServerProvider>);}

{key: "page-content",content: {  nodeType: "translation",  translation: {    en: {      getStartedByEditingThis: "Get started by editing this!",    },    fr: {      getStartedByEditingThis: "Commencez par éditer ceci !",    },    tr: {      getStartedByEditingThis: "Bunu düzenleyerek başlayın!",    },  }}}

import { type FC } from "react";import { IntlayerServerProvider, useIntlayer } from "next-intlayer/server";import { getLocale } from "next-intlayer/server";const PageContent: FC = () => {const content = useIntlayer("page-content");return (  <>    <p>{content.getStartedByEditingThis}</p>    <code>src/app/page.tsx</code>  </>);};export default async function Page() {const locale = await getLocale();return (  <IntlayerServerProvider locale={locale}>    <PageContent />  </IntlayerServerProvider>);}

• IntlayerClientProvider, istemci tarafındaki bileşenlere dil sağlamak için kullanılır.

• IntlayerServerProvider ise sunucu tarafındaki alt bileşenlere dil sağlamak için kullanılır.

  Layout and page cannot share a common server context because the server context system is based on a per-request data store (via React's cache mechanism), causing each "context" to be re-created for different segments of the application. Placing the provider in a shared layout would break this isolation, preventing the correct propagation of the server context values to your server components.

(İsteğe bağlı) Adım 7: Eksik çevirileri doldurma

Intlayer, eksik çevirileri doldurmanıza yardımcı olacak bir CLI aracı sağlar. Kodunuzdaki eksik çevirileri test etmek ve doldurmak için intlayer komutunu kullanabilirsiniz.

npx intlayer test         # Eksik çeviri olup olmadığını test et

npx intlayer fill         # Eksik çevirileri doldur

Daha fazla ayrıntı için CLI belgelerine bakın.

(İsteğe Bağlı) Adım 8: Yerelleştirilmiş Yönlendirme Proxy Ara Yazılımı

Kullanıcıları otomatik olarak tercih ettikleri dildeki URL'ye yönlendirmek istiyorsanız, bir proxy ara yazılımı (middleware) kurun:

export { intlayerProxy as proxy } from "next-intlayer/proxy";export const config = {  matcher:    "/((?!api|static|assets|robots|sitemap|sw|service-worker|manifest|.*\\..*|_next).*)",};

intlayerProxy, kullanıcının tercih ettiği dili algılamak ve yapılandırma dosyası ayarlarında belirtildiği gibi uygun URL'ye yönlendirmek için kullanılır. Ek olarak, kullanıcının tercih ettiği dilin bir çerezde saklanmasına olanak tanır.

(İsteğe Bağlı) Adım 9: İçerik Dilini Değiştirme

Next.js içinde içerik dilini değiştirmenin en önerilen yolu, kullanıcıları uygun dildeki rotaya yönlendirmek için Link bileşenini kullanmaktır. Bu, Next.js'in önceden getirme (prefetch) özelliğinden yararlanır ve sayfanın zorla yenilenmesini önler.

"use client";import type { FC } from "react";import { Locales, getHTMLTextDir, getLocaleName } from "intlayer";import { useLocale } from "next-intlayer";export const LocaleSwitcher: FC = () => {  const { locale, availableLocales, setLocale } = useLocale();  return (    <div>      <button popoverTarget="localePopover">{getLocaleName(locale)}</button>      <div id="localePopover" popover="auto">        {availableLocales.map((localeItem) => (          <button            key={localeItem}            aria-current={locale === localeItem ? "page" : undefined}            onClick={() => setLocale(localeItem)}          >            <span>              {/* Dil kodu - örn: TR */}              {localeItem}            </span>            <span>              {/* Kendi dilinde ad - örn: Türkçe */}              {getLocaleName(localeItem, locale)}            </span>            <span dir={getHTMLTextDir(localeItem)} lang={localeItem}>              {/* Mevcut dile göre ad - örn: Francés (mevcut dil Locales.SPANISH ise) */}              {getLocaleName(localeItem)}            </span>            <span dir="ltr" lang={Locales.ENGLISH}>              {/* İngilizce ad - örn: Turkish */}              {getLocaleName(localeItem, Locales.ENGLISH)}            </span>          </button>        ))}      </div>    </div>  );};

Alternatif olarak, useLocale hook'u tarafından sağlanan setLocale fonksiyonunu kullanabilirsiniz. Bu fonksiyon sayfanın önceden getirilmesine izin vermez. Daha fazla ayrıntı için useLocale hook belgelerine göz atın.

(İsteğe Bağlı) Adım 10: Bundle Boyutunu Optimize Etme

next-intlayer kullanıldığında, sözlükler varsayılan olarak her sayfanın paketi (bundle) içinde yer alır. Paket boyutunu optimize etmek için Intlayer, makroları kullanarak useIntlayer çağrılarını akıllıca değiştiren isteğe bağlı bir SWC eklentisi sağlar. Bu, sözlüklerin yalnızca onları gerçekten kullanan sayfaların paketlerine dahil edilmesini sağlar.

Bu optimizasyonu etkinleştirmek için @intlayer/swc paketini yükleyin. Yüklendikten sonra next-intlayer eklentiyi otomatik olarak algılayacak ve kullanacaktır:

npm install @intlayer/swc --save-dev

Not: Bu optimizasyon yalnızca Next.js 13 ve üzeri sürümlerde mevcuttur.

Not: Bu paket varsayılan olarak yüklü değildir çünkü SWC eklentileri Next.js'de hala deneysel aşamadadır. Bu durum gelecekte değişebilir.

Not: Eğer seçeneği (sözlük yapılandırmasında) importMode: 'dynamic' veya importMode: 'fetch' olarak ayarlarsanız, bu Suspense'e bağlı olacaktır, bu nedenle useIntlayer çağrılarınızı bir Suspense sınırı ile sarmalamanız gerekecektir. Bu, useIntlayer'ı doğrudan Sayfa / Layout bileşeninizin en üst düzeyinde kullanamayacağınız anlamına gelir.

TypeScript Yapılandırması

Intlayer, TypeScript'in avantajlarından yararlanmak ve kod tabanınızı daha sağlam hale getirmek için modül genişletmesini (module augmentation) kullanır.

TypeScript yapılandırmanızın otomatik olarak oluşturulan türleri içerdiğinden emin olun.

{  // ... Mevcut TypeScript yapılandırmalarınız  "include": [    // ... Mevcut TypeScript yapılandırmalarınız    ".intlayer/**/*.ts", // Otomatik oluşturulan türleri dahil edin  ],}

Git Yapılandırması

Intlayer tarafından oluşturulan dosyaların göz ardı edilmesi önerilir. Bu, onları Git deponuza yüklemekten kaçınmanıza olanak tanır.

Bunu yapmak için .gitignore dosyanıza aşağıdaki yönergeleri ekleyebilirsiniz:

# Intlayer tarafından oluşturulan dosyaları yoksay.intlayer

VS Code Eklentisi

Intlayer ile geliştirme deneyiminizi artırmak için resmi Intlayer VS Code eklentisini yükleyebilirsiniz.

VS Code Marketplace'ten yükleyin

Bu eklenti şunları sağlar:

• Çeviri anahtarları için otomatik tamamlama.
• Eksik çeviriler için gerçek zamanlı hata algılama.
• Çevrilmiş içeriğin satır içi önizlemeleri.
• Çevirileri kolayca oluşturmak ve güncellemek için hızlı eylemler (Quick actions).

Eklenti kullanımıyla ilgili detaylı talimatlar için Intlayer VS Code eklentisi belgelerini okuyun.

(İsteğe bağlı) Adım 11 : Bileşenlerinizin içeriğini çıkarın

Mevcut bir kod tabanınız varsa, binlerce dosyayı dönüştürmek zaman alıcı olabilir.

Bu süreci kolaylaştırmak için Intlayer, bileşenlerinizi dönüştürmek ve içeriği çıkarmak için bir derleyici / çıkarıcı sunar.

Kurulum için intlayer.config.ts dosyanıza bir compiler bölümü ekleyebilirsiniz:

import { type IntlayerConfig } from "intlayer";

const config: IntlayerConfig = {
  // ... Yapılandırmanızın geri kalanı
  compiler: {
    /**
     * Derleyicinin etkinleştirilip etkinleştirilmeyeceğini belirtir.
     */
    enabled: true,

    /**
     * Çıktı dosyalarının yolunu tanımlar
     */
    output: ({ fileName, extension }) => `./${fileName}${extension}`,

    /**
     * Bileşenlerin dönüştürüldükten sonra kaydedilip kaydedilmeyeceğini belirtir. Bu sayede derleyici, uygulamayı dönüştürmek için yalnızca bir kez çalıştırılabilir ve ardından kaldırılabilir.
     */
    saveComponents: false,

    /**
     * Sözlük anahtarı öneki
     */
    dictionaryKeyPrefix: "",
  },
};

export default config;

npx intlayer extract

npm install @intlayer/babel --save-dev

const { intlayerExtractBabelPlugin, getExtractPluginOptions,} = require("@intlayer/babel");module.exports = { presets: ["next/babel"], plugins: [   // Bileşenlerden içeriği sözlüklere çıkarın   [intlayerExtractBabelPlugin, getExtractPluginOptions()], ],};

npm run build # Veya npm run dev

Daha Fazlası

Daha ileri gitmek için görsel düzenleyiciyi uygulayabilir veya CMS kullanarak içeriğinizi dışsallaştırabilirsiniz.