react-i18next / i18next'ten Intlayer'a Geçiş

Neden react-i18next / i18next'ten Intlayer'a geçmelisiniz?

Geçiş Stratejileri

react-i18next / i18next'ten Intlayer'a geçiş yapmak için birbirini tamamlayan iki strateji vardır:

1. Uyumluluk Adaptörü (Mevcut uygulamalar için önerilir) — @intlayer/react-i18next (React bileşenleri için) ve/veya @intlayer/i18next (kök i18n örneği (instance) için) paketlerini kurun. Bu paketler arka planda tüm çeviri işlerini Intlayer'a devrederek react-i18next / i18next ile tam olarak aynı API'yi sunar. Mevcut useTranslation, Trans, withTranslation, i18next.t() kullanımınız dokunulmadan kalır; değişen tek şey içe aktarma yoludur.

2. Tam Geçiş — react-i18next API'lerini kademeli olarak Intlayer'ın yerel (native) araçlarıyla (useIntlayer, IntlayerProvider) 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 react-i18next uygulamanızı hiçbir 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örünü kurun:

   bash

   İçeriği kopyala

   Kodu kopyala

   Kodu panoya kopyala

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

   react-i18next ve i18next'i güvenle yüklü bırakabilirsiniz; uyumluluk adaptörü bunları TypeScript türleri için devDependency / peerDependency olarak kullanır. package.json dosyanızdaki herhangi bir eş bağımlılığı (peer dependency) değiştirmeniz gerekmez.

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({
         // react-i18next yer tutucu sentaksıyla eşleşir: {{name}}
         format: "i18next",
         source: ({ locale }) => `./src/locales/${locale}.json`,
         location: "src/locales",
       }),
     ],
   };
   
   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: 'i18next' seçeneği, {{name}} gibi yer tutucuların (placeholder) doğru bir şekilde çözümlenmesini garanti eder.

3. 3

   Intlayer Eklentilerini Paketleyiciye (Bundler) Ekleyin

   Mevcut bundler yapılandırmanızı uyumluluk eklentisiyle sarmalayın. Bu işlem, temel Intlayer eklentisini dâhil eder, içerik izlemeyi etkinleştirir ve en önemlisi modül takma adları (alias) enjekte eder. Böylece import … from 'react-i18next' (ve 'i18next') komutları derleme aşamasında şeffaf bir şekilde @intlayer/react-i18next / @intlayer/i18next adresine yönlendirilir. Kaynak kodunda hiçbir değişiklik yapmanıza gerek yoktur.

   Vite İçin:

   vite.config.ts

   İçeriği kopyala

   Kodu kopyala

   Kodu panoya kopyala

   import { defineConfig } from "vite";
   import react from "@vitejs/plugin-react";
   import { reactI18nextVitePlugin } from "@intlayer/react-i18next/plugin";
   
   export default defineConfig({
     plugins: [react(), reactI18nextVitePlugin()],
   });

   reactI18nextVitePlugin(), vite-intlayer altındaki normal intlayer() eklentisini sarmalar ve react-i18next / i18next takma adlarını (alias) otomatik olarak ekler. Düzenli intlayer() vite-intlayer eklentisini kullanmak sözlükleri derler ancak alias eklemez; bu durumda içe aktarmaları manuel olarak @intlayer/* olarak yeniden adlandırmanız gerekir (Adım 4'e bakın).

   Next.js İçin:

   Eğer next-i18next (Pages Router entegrasyonu) kullanıyorsanız, @intlayer/next-i18next ve next-intlayer kurun:

   bash

   İçeriği kopyala

   Kodu kopyala

   Kodu panoya kopyala

   npm install @intlayer/next-i18next next-intlayer

   Sonra uyumluluk eklentisini next.config.ts dosyanıza ekleyin (bu, next-i18next / react-i18next / i18next için takma ad (alias) enjekte edecektir):

   next.config.ts

   İçeriği kopyala

   Kodu kopyala

   Kodu panoya kopyala

   import type { NextConfig } from "next";
   import { createNextI18nPlugin } from "@intlayer/next-i18next/plugin";
   
   const withIntlayer = createNextI18nPlugin();
   
   const nextConfig: NextConfig = {
     /* diğer yapılandırma ayarlarınız */
   };
   
   export default withIntlayer(nextConfig);

   i18next.init() veya manuel provider çağrıları artık gerekli değildir. Intlayer tüm sözlükleri derleme (build) zamanında derler ve çalışma zamanında (runtime) yükleme adımını ortadan kaldırır. Alias yönlendirmesiyle sarmalanmış Provider başlatma (initialization) işlemini kendi halleder.

Hızlı geçiş bu kadar. Uygulamanız artık react-i18next 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, 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

// 'about' kayıtlı bir sözlüktür → t() sadece geçerli yolları kabul ederconst { t } = useTranslation("about");t("counter.label"); // ✓ otomatik tamamlandıt("does.not.exist"); // ✗ TypeScript Hatası// Sunucu (Server) Tarafı (i18next örneği)const tAbout = i18n.getFixedT(null, "about");tAbout("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ı

   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 { useTranslation } from 'react-i18next'	import { useTranslation } from '@intlayer/react-i18next'
   import { Trans } from 'react-i18next'	import { Trans } from '@intlayer/react-i18next'
   import { withTranslation } from 'react-i18next'	import { withTranslation } from '@intlayer/react-i18next'
   import { I18nextProvider } from 'react-i18next'	import { I18nextProvider } from '@intlayer/react-i18next'
   import { initReactI18next } from 'react-i18next'	import { initReactI18next } from '@intlayer/react-i18next'
   import i18next from 'i18next'	import i18next from '@intlayer/i18next'
   import { createInstance } from 'i18next'	import { createInstance } from '@intlayer/i18next'
   import { t } from 'i18next'	import { t } from '@intlayer/i18next'

   Next.js (next-i18next) İçin:

   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'

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: ({ locale }) => `./src/locales/${locale}.json`,
         location: "src/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 react-i18next / 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
• React İle Intlayer — React için tam kurulum rehberi: intlayerwithvite+react.md
• Next.js İle Intlayer — Next.js için tam kurulum rehberi: intlayerwithnextjs_16.md