next-i18next'ten Intlayer'a Geçiş

Neden next-i18next'ten Intlayer'a geçmelisiniz?

Geçiş Stratejileri

next-i18next, react-i18next ve i18next üzerine kurulu olduğundan, Intlayer'a geçiş için birbirini tamamlayan iki strateji vardır:

1. Uyumluluk Adaptörü (Mevcut uygulamalar için önerilir) — @intlayer/next-i18next, @intlayer/react-i18next ve @intlayer/i18next paketlerini kurun. Bu paketler arka planda tüm çeviri işlerini Intlayer'a devrederek eskisi ile tam olarak aynı API'leri sunar. Mevcut useTranslation, appWithTranslation, serverSideTranslations çağrılarınız ve Next.js Sayfa Yönlendirici (Pages Router) yapılarınız dokunulmadan kalır; değişen tek şey kurulum ve yapılandırma şeklidir.

2. Tam Geçiş — next-i18next API'lerini kademeli olarak Intlayer'ın yerel (native) kancalarıyla (useIntlayer) değiştirin ve içeriğinizi bileşenlerinizin yanındaki .content.ts dosyalarında tutun (colocate).

Bu kılavuz, öncelikle Strateji 1'i (doğrudan eklenebilir uyumluluk adaptörü) kapsar ve ardından isteğe bağlı tam geçişten bahseder.

İçindekiler

Hızlı Geçiş

Aşağıdaki adımlar, mevcut Next.js (Pages Router) uygulamanızı hiçbir sayfa veya bileşen kodunu değiştirmeden Intlayer üzerinde çalıştırmak için gereken minimum işlemlerdir.

1. 1

   Bağımlılıkları Kurun

   Temel Intlayer paketlerini ve uyumluluk adaptörlerini kurun:

   bash

   İçeriği kopyala

   Kodu kopyala

   Kodu panoya kopyala

   npm install intlayer next-intlayer react-intlayer @intlayer/next-i18next @intlayer/react-i18next @intlayer/i18next @intlayer/sync-json-pluginnpx intlayer init

   Geçiş sürecinde ve alias'lar çözümlenene kadar next-i18next, react-i18next ve i18next kurulumlarını güvenle koruyabilirsiniz.

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ı (genellikle public/locales dizininde bulunur) 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({
         // i18next yer tutucu sentaksıyla eşleşir: {{name}}
         format: "i18next",
         source: ({ key, locale }) => `./public/locales/${locale}/${key}.json`,
         location: "public/locales",
       }),
     ],
   };
   
   export default config;

   source, bir dili ve namespace'i (key) JSON dosya yolunuza eşler. location, Intlayer izleyicisine (watcher) değişiklikler için hangi klasörü izlemesi gerektiğini söyler. format: 'i18next' seçeneği, next-i18next yer tutucularının doğru bir şekilde çözümlenmesini garanti eder.

3. 3

   Next.js Yapılandırmanızı Güncelleyin

   Mevcut next.config.ts (veya .js) dosyanızı @intlayer/next-i18next/plugin tarafından sağlanan createNextI18nPlugin fonksiyonuyla sarın. Bu sarmalayıcı (wrapper) fonksiyon, withIntlayerı uygular ve eşzamanlı olarak next-i18next / react-i18next / i18next → @intlayer/* takma adlarını (alias) enjekte eder; böylece import { useTranslation } from 'next-i18next' şeklindeki çağrılarınız yapı (build) aşamasında şeffaf bir şekilde yeniden yönlendirilir. Kod tabanınızda hiçbir değişiklik yapmanız gerekmez.

   next.config.ts

   İçeriği kopyala

   Kodu kopyala

   Kodu panoya kopyala

   import type { NextConfig } from "next";
   import { createNextI18nPlugin } from "@intlayer/next-i18next/plugin";
   // next-i18next.config.js'den gelen i18n yapılandırma içe aktarması kaldırılabilir
   // import { i18n } from './next-i18next.config';
   
   const withIntlayer = createNextI18nPlugin();
   
   const nextConfig: NextConfig = {
     // Intlayer yerleşik Next.js i18n yönlendirmesini (routing) kendi altında yönetir,
     // bu yüzden i18n nesnesini burada iletmenize gerek kalmaz.
   };
   
   export default withIntlayer(nextConfig);

   next-i18next.config.js dosyasına artık ihtiyacınız yok. Intlayer tüm sözlükleri derleme (build) zamanında derler, dil tespitini, yönlendirmeyi ve sözlük yüklemesini sorunsuz bir şekilde ele alır.

   next-intlayer/server'dan saf withIntlayer eklentisini mi tercih ediyorsunuz? Bu yöntemi kullanırsanız sözlükler derlenecektir ancak next-i18next / react-i18next / i18next takma adları (aliases) eklenmeyecektir; bu durumda içe aktarmaları @intlayer/* şeklinde manuel olarak yeniden adlandırmanız gerekecektir (Adım 4'e bakın).

Hızlı geçiş bu kadar. Next.js uygulamanız artık, useTranslation, serverSideTranslations ve appWithTranslation çağrılarınızı olduğu gibi koruyarak Intlayer üzerinde çalışmaktadır.

Türetilmiş (Typed) çeviri anahtarları — otomatik olarak. Intlayer sözlüklerinizi derlediğinde, useTranslation ve getFixedT kendi gerçek içeriğiniz için tür güvenli (typed) hale gelir. Anahtarlar IDE'nizde otomatik tamamlanır (autocomplete) ve geçersiz yollar, ekstra bir yapılandırma olmadan derleme (compile) anında TypeScript hatalarına neden olur.

tsx

İçeriği kopyala

Kodu kopyala

Kodu panoya kopyala

// Pages Router — 'about' kayıtlı bir sözlük isim alanıdır (namespace)const { t } = useTranslation("about");t("counter.label"); // ✓ otomatik tamamlandıt("does.not.exist"); // ✗ TypeScript Hatası// getStaticProps / getServerSideProps (i18next örneği)const tAbout = i18n.getFixedT(null, "about");tAbout("counter.label"); // ✓ tür güvenli

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ı

   Intlayer eklentisi takma adlama (aliasing) işlemlerini bundler düzeyinde çoktan halleder. Bağımlılığı kaynak dosyalarınızda açık tutmayı tercih ederseniz, içe aktarma yollarını manuel olarak yeniden adlandırabilirsiniz:

   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 { serverSideTranslations } from 'next-i18next/serverSideTranslations'	import { serverSideTranslations } from '@intlayer/next-i18next'
   import { appWithTranslation } from 'next-i18next'	import { appWithTranslation } from '@intlayer/next-i18next'
   import { useTranslation } from 'next-i18next'	import { useTranslation } from '@intlayer/next-i18next'
   import { useTranslation } from 'react-i18next'	import { useTranslation } from '@intlayer/react-i18next'

   Bunlar doğrudan değişimlerdir; fonksiyon çağırma şeklinizde, argümanlarda veya dönüş türlerinde hiçbir değişiklik gerekmez.

2. 5

   AI Çeviri Otomasyonunu Etkinleştirin

   İsteğe bağlı

   Intlayer yapılandırıldığında, 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

   AI yapılandırmanızı intlayer.config.ts dosyasına ekleyin:

   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: "i18next",
         source: ({ key, locale }) => `./public/locales/${locale}/${key}.json`,
         location: "public/locales",
       }),
     ],
     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

Uyumluluk adaptörü kullanılmaya başlandığında, aşağıdaki standart next-i18next 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 MyComponent.tsx'in yanına bir my-component.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 (Pages Router) ile Intlayer — Next.js için tam kurulum rehberi: intlayerwithnextjspagerouter.md