Creation:2026-01-10Last update:2026-05-31

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

    www.youtube.com

    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

    1. Bağımlılıkları Yükleyin

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

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

    2. Projenizi Yapılandırın

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

      intlayer.config.ts
      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.

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

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

      next.config.ts
      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.

    4. Sayfanızda Dil Algılama

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

      src/app/layout.tsx
      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;

    5. İçeriğinizi Tanımlayın

      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:

      src/app/page.tsx
      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>);}
      • 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.

    6. Eksik çevirileri doldurma

      İsteğe bağlı

      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.

      bash
      npx intlayer test         # Eksik çeviri olup olmadığını test et
      bash
      npx intlayer fill         # Eksik çevirileri doldur
      Daha fazla ayrıntı için CLI belgelerine bakın.

    7. Yerelleştirilmiş Yönlendirme Proxy Ara Yazılımı

      İsteğe bağlı

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

      src/proxy.ts
      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.

    8. İçerik Dilini Değiştirme

      İsteğe bağlı

      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.

      src/components/localeSwitcher/LocaleSwitcher.tsx
      "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.

    9. Bundle Boyutunu Optimize Etme

      İsteğe bağlı

      next-intlayer kullanıldığında, sözlükler varsayılan olarak her sayfanın paketi (bundle) içinde yer alır. bundle 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:

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

    10. Bileşenlerinizin içeriğini çıkarın

      İsteğe bağlı

      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:

      intlayer.config.ts
      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;

      Bileşenlerinizi dönüştürmek ve içeriği çıkarmak için çıkarıcıyı çalıştırın

      bash
      npx intlayer extract

    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:

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

    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.

    Otomatik tamamlama

    Çeviri hatası

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

    tsconfig.json
    {  // ... 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:

    .gitignore
    # 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.

    Daha Fazlası

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

    Next.js ve Sayfa Yönlendirici
    Tanstack Start