next-intl'den Intlayer'a Geçiş

Neden next-intl'den Intlayer'a geçmelisiniz?

Geçiş Stratejisi

Mevcut uygulamalar için önerilen yaklaşım, uyumluluk adaptörünü kullanmaktır: @intlayer/next-intl paketini kurun. Bu paket, arka planda tüm çeviri işini Intlayer'a devrederek next-intl ile tamamen aynı API'yi sunar.

useTranslations, getTranslations, NextIntlClientProvider vb. mevcut dosyalarınızda olduğu gibi kalır; değişen tek şey içe aktarma yoludur. Herhangi bir çağrı sentaksını, özellik (props) adını veya bileşen kurgunuzu değiştirmeniz gerekmez.

Zamanla, görsel editör, CMS ve bileşen düzeyi bağlamından (scoping) yararlanmak için bağımsız dosyaları yavaş yavaş Intlayer'ın daha güçlü .content.ts biçimine dönüştürebilirsiniz—fakat bu adım tamamen isteğe bağlıdır ve adım adım uygulanabilir.

İçindekiler

Hızlı Geçiş

Aşağıdaki adımlar, mevcut next-intl uygulamanızı herhangi bir kod değişikliği yapmadan Intlayer üzerinde çalıştırmak için gereken minimum işlemlerdir.

1. 1

   Bağımlılıkları Kurun

   Temel Intlayer paketlerini ve @intlayer/next-intl uyumluluk adaptörünü kurun:

   bash

   İçeriği kopyala

   Kodu kopyala

   Kodu panoya kopyala

   npm install intlayer next-intlayer @intlayer/next-intl @intlayer/sync-json-pluginnpx intlayer init

   next-intl'i yüklü bırakın; URL yönlendirmesi (routing) için (createNavigation, createMiddleware, Link, redirect, usePathname, useRouter) gereklidir. Uyumluluk adaptörü yönlendirme katmanını değiştirmez.

2. 2

   Intlayer'ı Yapılandırın

   intlayer init komutu başlangıç olarak bir intlayer.config.ts dosyası oluşturur. Bunu mevcut yerel ayarlarınıza (locales) uyacak şekilde güncelleyin ve mesaj dosyalarınızı syncJSON eklentisine işaret edin:

   intlayer.config.ts

   İçeriği kopyala

   Kodu kopyala

   Kodu panoya kopyala

   import { Locales, type IntlayerConfig } from "intlayer";
   import { syncJSON } from "@intlayer/sync-json-plugin";
   
   const config: IntlayerConfig = {
     internationalization: {
       locales: [
         Locales.ENGLISH,
         Locales.FRENCH,
         Locales.SPANISH,
         // Mevcut diğer dillerinizi (locales) buraya ekleyin
       ],
       defaultLocale: Locales.ENGLISH,
     },
     plugins: [
       syncJSON({
         // 'icu', next-intl'nin ICU yer tutucu formatıyla eşleşir: {name}, {count, plural, ...}
         format: "icu",
         source: ({ locale }) => `./messages/${locale}.json`,
         location: "messages",
       }),
     ],
   };
   
   export default config;

   source, bir dili JSON dosya yolunuza eşler. location, Intlayer izleyicisine (watcher) değişiklikler için hangi klasörü izlemesi gerektiğini söyler. format: 'icu' seçeneği, {name} ve {count, plural, one {# item} other {# items}} gibi ICU yer tutucularının (placeholder) doğru bir şekilde çözümlenmesini garanti eder.

   Mevcut tüm seçeneklerin tam listesi için Yapılandırma Dokümantasyonuna göz atın.

3. 3

   Intlayer Eklentisini Next.js'e Entegre Edin

   Mevcut Next.js konfigürasyonunuzu @intlayer/next-intl/plugin paketindeki createNextIntlPlugin fonksiyonu ile sarmalayın. Bu eklenti withIntlayer kuralını uygular ve eşzamanlı olarak next-intl → @intlayer/next-intl takma ad (alias) enjeksiyonunu otomatik olarak kaydeder:

   next.config.ts

   İçeriği kopyala

   Kodu kopyala

   Kodu panoya kopyala

   import type { NextConfig } from "next";
   import { createNextIntlPlugin } from "@intlayer/next-intl/plugin";
   
   const withIntlayer = createNextIntlPlugin();
   
   const nextConfig: NextConfig = {
     /* Mevcut Next.js seçenekleriniz */
   };
   
   export default withIntlayer(nextConfig);

   createNextIntlPlugin(), withIntlayer'ı sarmalar, Webpack veya Turbopack'i otomatik algılar, içerik izleyicisini bağlar, sözlükleri ön derler ve en önemlisi modül takma adları (alias) enjekte eder. Böylece mevcut import … from 'next-intl' çağrıları derleme aşamasında otomatik olarak @intlayer/next-intl adresine yönlendirilir. next-intl/routing gibi yönlendirme içe aktarmaları gerçek pakete yönlendirilmeye devam edecektir. Kaynak kodunda hiçbir değişiklik yapmanıza gerek yoktur.

   Eğer saf withIntlayer (sadece next-intlayer/server kullanarak) eklentisini tercih ederseniz, bu durumda sözlükleriniz derlenecektir ancak takma adlar (aliases) eklenmeyecektir. İçe aktarmaları @intlayer/next-intl olarak manuel olarak yeniden adlandırmanız gerekecektir (Adım 4'e bakın).

   getRequestConfig yapılandırması ya da mesaj yüklemek artık gerekli değildir. next-intl için src/i18n.ts adında, getRequestConfig üzerinden her istek (request) için JSON mesaj paketlerini yükleyen bir dosya oluşturmanız gerekirdi. Intlayer tüm sözlükleri derleme (build) anında derlediği için istek (request) başı ayrı mesaj yükleme adımına ihtiyaç kalmamaktadır. Bu dosyayı güvenle silebilirsiniz (eğer createNavigation için kullanıyorsanız sadece yönlendirme (routing) satırlarını tutabilirsiniz).

Hızlı geçiş bu kadar. Uygulamanız artık next-intl içe aktarmalarınız ve API'niz olduğu gibi kalarak Intlayer üzerinde çalışmaktadır.

Türetilmiş (Typed) çeviri anahtarları — otomatik olarak. Intlayer sözlüklerinizi derlediğinde, useTranslations ve getTranslations özellikleri, kendi gerçek içeriğiniz için tam anlamıyla tür güvenli (typed) hale gelir. IDE'nizdeki anahtarlar otomatik tamamlanacak (autocomplete) ve geçersiz yollar herhangi bir ilave yapılandırma gerektirmeden derleme zamanında TypeScript hatası üretecektir.

tsx

İçeriği kopyala

Kodu kopyala

Kodu panoya kopyala

// İstemci bileşeni (Client component) — 'about' kayıtlı bir sözlük anahtarıdırconst t = useTranslations("about");t("counter.label"); // ✓ otomatik tamamlandıt("does.not.exist"); // ✗ TypeScript Hatası// Sunucu bileşeni (Server component)const t = await getTranslations("about");t("counter.label"); // ✓ tür güvenli (typed)

Tam Geçiş

Aşağıdaki adımlar isteğe bağlıdır ve kademeli olarak yapılabilir. Bunlar, görsel editör, CMS, türetilmiş (typed) içerik dosyaları, AI çeviri otomasyonu gibi Intlayer özelliklerinin tam kapsamlı kullanımını sağlar.

1. 4

   İçe Aktarmaları Açıkça Yeniden Adlandırın (İsteğe Bağlı)

   İsteğe bağlı

   createNextIntlPlugin() sarmalayıcısı (wrapper) bundler tarafında next-intl → @intlayer/next-intl takma adlamasını (aliasing) otomatik gerçekleştirir. Bağımlılığı kaynak dosyalarınızda açık tutmayı tercih ederseniz (ve karşılığında standart saf withIntlayer eklentisini kullanmak isterseniz), içe aktarmaları manuel olarak şu şekilde değiştirebilirsiniz:

   Tüm tablo içeriğini göster

   Tüm tablo içeriğini göster

   Tüm veri içeriğini net bir şekilde görmek için tabloyu modalde açın

   Öncesi	Sonrası
   import { useTranslations } from 'next-intl'	import { useTranslations } from '@intlayer/next-intl'
   import { useLocale } from 'next-intl'	import { useLocale } from '@intlayer/next-intl'
   import { NextIntlClientProvider } from 'next-intl'	import { NextIntlClientProvider } from '@intlayer/next-intl'
   import { getTranslations } from 'next-intl/server'	import { getTranslations } from '@intlayer/next-intl/server'
   import { getLocale } from 'next-intl/server'	import { getLocale } from '@intlayer/next-intl/server'
   import { setLocale } from 'next-intl/server'	import { setLocale } from '@intlayer/next-intl/server'
   import { getMessages } from 'next-intl/server'	import { getMessages } from '@intlayer/next-intl/server'

   Yönlendirme ile ilgili içe aktarmaların her zaman gerçek next-intl'den geldiğinden emin olun — uyumluluk adaptörü next-intl'nin URL yönlendirme işleyişini değiştirmez:

   ts

   İçeriği kopyala

   Kodu kopyala

   Kodu panoya kopyala

   // ✅ Bunları gerçek 'next-intl' paketinden almayı sürdürünimport { createNavigation } from "next-intl/routing";import { createMiddleware } from "next-intl/server";import { defineRouting } from "next-intl/routing";

   Alternatif olarak, @intlayer/next-intl/routing içindeki defineRouting'i kullanmak, ortamları intlayer.config.ts dosyanızla otomatik olarak birleştirebilir.

2. 5

   AI Çeviri Otomasyonunu Etkinleştirin

   İsteğe bağlı

   Intlayer yapılandırıldığında, seçtiğiniz bir LLM modeliyle eksik çevirileri otomatik olarak doldurmak için CLI'yı kullanabilirsiniz:

   bash

   İçeriği kopyala

   Kodu kopyala

   Kodu panoya kopyala

   # Eksik çevirileri test et (CI'a ekleyin)npx intlayer test# Eksik çevirileri AI kullanarak doldurnpx intlayer fill

   OPENAI_API_KEY (veya desteklenen başka bir anahtar) değişkeninizi yerel .env dosyanıza ekleyin ve sonrasında intlayer.config.ts dosyanızı güncelleyin:

   intlayer.config.ts

   İçeriği kopyala

   Kodu kopyala

   Kodu panoya kopyala

   import { Locales, type IntlayerConfig } from "intlayer";
   import { syncJSON } from "@intlayer/sync-json-plugin";
   
   const config: IntlayerConfig = {
     internationalization: {
       locales: [Locales.ENGLISH, Locales.FRENCH, Locales.SPANISH],
       defaultLocale: Locales.ENGLISH,
     },
     plugins: [
       syncJSON({
         format: "icu",
         source: ({ locale }) => `./messages/${locale}.json`,
         location: "messages",
       }),
     ],
     ai: {
       apiKey: process.env.OPENAI_API_KEY,
       // provider: "openai",     // varsayılan
       // model: "gpt-4o-mini",   // varsayılan
     },
   };
   
   export default config;

   Mevcut tüm seçenekleri incelemek için Intlayer CLI Dokümantasyonuna göz atın.

Geçişten Sonra Silinebilecekler

@intlayer/next-intl kullanılmaya başlandığında, aşağıdaki standart next-intl tekrarlayan kodları (boilerplate) kaldırılabilir:

Bir adım öteye geçmeye hazır olduğunuzda, Intlayer kod tabanınızın herhangi bir yerindeki (varsayılan olarak ./src altındaki herhangi bir yerde) tüm .content.ts ve .content.json dosyalarını otomatik olarak keşfeder. Sadece about/page.tsx'in yanına bir about.content.ts dosyası bırakın, Intlayer onu ek bir yapılandırma olmadan derleme (build) sırasında yakalayacaktır. Ne içe aktarmaya, ne kayda, ne de merkezi bir indeks dosyasına ihtiyaç vardır. Bu sayede çeviriler sayfalar ve bileşenlerinizle en kolay şekilde bir arada tutulur (colocation).

TypeScript Kurulumu

Intlayer, çeviri anahtarlarınız için kapsamlı TypeScript IntelliSense'i (otomatik tamamlama) sağlamak için modül genişletme (module augmentation) özelliğini kullanır. tsconfig.json dosyanızın otomatik 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 içeriğe dahil edin  ],}

Git Yapılandırması

Intlayer tarafından oluşturulan dizini .gitignore dosyanıza ekleyin:

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

Daha Fazlasını Keşfedin

• Görsel Editör — Çevirileri doğrudan tarayıcınızda görsel olarak yönetin: Intlayer Görsel Editör
• CMS — İçeriği projenizden ayırın ve uzaktan yönetin: Intlayer CMS
• VS Code Eklentisi — Otomatik tamamlama ve anında hata tespiti (hover) edinin: Intlayer VS Code Eklentisi
• CLI Referansı — CLI komutlarının tam listesi: Intlayer CLI
• Next.js İle Intlayer — Next.js için tam kurulum rehberi: intlayerwithnextjs_16.md