Gereksinimler ve Ön Hazırlık

Çalışmaya başlamadan önce bilgisayarınızda Node.js'in güncel bir sürümünün (2026 itibarıyla LTS sürümü önerilir) kurulu olduğundan emin olun. Projenizi başlatmak için Vite gibi modern bir yapılandırıcı kullanmanız önerilir.

Öncelikle gerekli paketleri projenize dahil etmeniz gerekmektedir. Terminalinizi açın ve proje dizininizde aşağıdaki komutu çalıştırın:

npm install i18next react-i18next i18next-browser-languagedetector i18next-http-backend

Bu paketlerin her biri farklı bir amaca hizmet eder: i18next temel motoru sağlar, react-i18next React entegrasyonunu sunar, i18next-browser-languagedetector kullanıcının tarayıcı dilini otomatik algılar ve i18next-http-backend ise çeviri dosyalarını dışarıdan yüklemek için kullanılır.

I18next Konfigürasyonu ve İlk Kurulum

I18next'i projenize tanıtmak için bir yapılandırma dosyası oluşturmalısınız. Genellikle src/i18n.js adında bir dosya oluşturmak en temiz yöntemdir. Bu dosya, kütüphanenin nasıl davranacağını belirler.

import i18n from 'i18next';
import { initReactI18next } from 'react-i18next';
import LanguageDetector from 'i18next-browser-languagedetector';
import HttpApi from 'i18next-http-backend';

i18n.use(initReactI18next)
  .use(LanguageDetector)
  .use(HttpApi)
  .init({
    supportedLngs: ['tr', 'en'],
    fallbackLng: 'tr',
    detection: {
      order: ['cookie', 'localStorage', 'htmlTag'],
      caches: ['cookie'],
    },
    backend: {
      loadPath: '/assets/locales/{{lng}}/translation.json',
    },
  });

export default i18n;

Bu kod bloğu, uygulamanın hangi dilleri destekleyeceğini ve çeviri dosyalarının nerede bulunacağını tanımlar. fallbackLng, eğer kullanıcının dili tanımlı değilse varsayılan olarak Türkçe'nin kullanılacağını belirtir.

Çeviri Dosyalarının Oluşturulması

Çeviriler, JSON formatında tutulur. public/assets/locales/tr/translation.json ve public/assets/locales/en/translation.json dosyalarını oluşturun. Bu yapı, projenizin ölçeklenebilir olmasını sağlar.

// public/assets/locales/tr/translation.json
{
  "welcome": "Hoş geldiniz",
  "description": "Bu bir React çoklu dil uygulamasıdır."
}

// public/assets/locales/en/translation.json
{
  "welcome": "Welcome",
  "description": "This is a React multi-language application."
}

JSON dosyalarındaki anahtarlar (key) her iki dilde de aynı olmalıdır. Değerler ise ilgili dile göre çevrilmelidir. Bu sayede kodunuzda sadece anahtarı kullanmanız yeterli olacaktır.

React Bileşenlerinde Çeviri Kullanımı

Şimdi oluşturduğumuz bu yapılandırmayı React bileşenlerimizde kullanalım. useTranslation hook'u, çevirilere erişmek için en yaygın ve modern yöntemdir.

import { useTranslation } from 'react-i18next';

function App() {
  const { t } = useTranslation();

  return (
    

      
{t('welcome')}
      
{t('description')}
    
  );
}

Buradaki t fonksiyonu, verdiğiniz anahtarı mevcut seçili dildeki karşılığıyla değiştirir. Bu işlem otomatik olarak gerçekleşir; yani dil değiştiğinde bileşen yeniden render olur ve yeni metinler görünür.

Dil Değiştirme Fonksiyonelliği

Kullanıcının dili değiştirebilmesi için bir arayüz bileşeni oluşturmalıyız. i18n.changeLanguage metodu bu iş için kullanılır.

import { useTranslation } from 'react-i18next';

function LanguageSwitcher() {
  const { i18n } = useTranslation();

  const changeLanguage = (lng) => {
    i18n.changeLanguage(lng);
  };

  return (
    

       changeLanguage('tr')}>Türkçe
       changeLanguage('en')}>English
    
  );
}

Bu bileşen, kullanıcı butonlara tıkladığında i18next'in dil durumunu günceller. Uygulamanın geri kalanı bu değişikliği algılar ve tüm metinleri anında günceller.

Çoklu Dil Yönetimi Yöntemlerinin Karşılaştırılması

Güvenlik Uyarısı: Çeviri dosyalarınızda kullanıcıdan gelen verileri doğrudan kullanmayın. Eğer çeviri metinleri içinde değişken değerler (örneğin kullanıcı adı) gösterecekseniz, XSS (Cross-Site Scripting) saldırılarına karşı react-i18next'in sağladığı güvenli interpolation yöntemlerini kullanın.

Sıkça Sorulan Sorular

I18next ile tarih ve sayı formatları nasıl yerelleştirilir?

I18next tek başına sayı ve tarih formatlamaz. Bunun için i18next-icu veya standart JavaScript Intl API'sini kullanmanız önerilir.

Çeviri dosyaları çok büyürse ne yapmalıyım?

Çeviri dosyalarını sayfa bazlı parçalara ayırabilir ve sadece ihtiyaç duyulan sayfada ilgili çeviri dosyasını yükleyebilirsiniz (Lazy Loading).

Kullanıcının dili tarayıcıdan nasıl algılanır?

i18next-browser-languagedetector paketi, tarayıcının navigator.language ayarını otomatik olarak okur ve uygulamayı bu dilde başlatır.

Dil değiştiğinde sayfa yenilenmeli mi?

Hayır, I18next React entegrasyonu sayesinde dil değişikliği anında (hot-reload) gerçekleşir, sayfa yenilemeye gerek kalmaz.

SEO için çoklu dil desteği nasıl optimize edilir?

URL yapınızda dil kodlarını kullanın (örneğin: site.com/tr/ veya site.com/en/) ve hreflang etiketlerini doğru yapılandırın.

I18next ile Gelişmiş Hata Ayıklama ve Loglama

Çok dilli uygulamalarda çeviri anahtarlarının eksik olması veya yanlış yapılandırılması, kullanıcı deneyimini doğrudan olumsuz etkiler. Geliştirme aşamasında bu sorunları hızlıca tespit etmek için i18next'in sunduğu hata ayıklama (debugging) özelliklerini aktif etmelisiniz. i18next-debug-backend veya doğrudan konfigürasyon içerisindeki debug: true parametresi, konsol üzerinde hangi anahtarın bulunamadığını ve hangi dilin yüklendiğini detaylıca gösterir.

Aşağıdaki örnekte, eksik çevirileri yakalamak ve geliştirici konsolunda uyarı oluşturmak için kullanılan yapılandırmayı görebilirsiniz:

import i18n from 'i18next';
import { initReactI18next } from 'react-i18next';

i18n.use(initReactI18next).init({
  resources: { /* ... */ },
  lng: 'tr',
  debug: true, // Geliştirme ortamında hataları konsola yansıtır
  saveMissing: true, // Eksik çevirileri backend'e göndermek için tetikleyici
  missingKeyHandler: (lng, ns, key, fallbackValue) => {
    console.warn(`Eksik çeviri anahtarı bulundu: ${key} (${lng} dilinde)`);
  }
});

Performans Optimizasyonu: Lazy Loading ve Namespace Bölümleme

Uygulamanız büyüdükçe, tüm çeviri dosyalarını başlangıçta yüklemek (bundle) tarayıcı performansını düşürebilir. Bunun önüne geçmek için i18next-http-backend kullanarak çeviri dosyalarını sadece ihtiyaç duyulduğunda (lazy loading) çekmelisiniz. Ayrıca, çeviri dosyalarınızı "namespace" (isim alanı) mantığıyla bölümlere ayırmak, bellek kullanımını optimize eder.

Örneğin, auth.json, dashboard.json ve settings.json gibi dosyalar oluşturarak sadece ilgili sayfa yüklendiğinde ilgili dosyanın çekilmesini sağlayabilirsiniz:

// Bileşen içerisinde belirli bir namespace'i yükleme
import { useTranslation } from 'react-i18next';

function SettingsPage() {
  // Sadece 'settings' namespace'ini yükle
  const { t } = useTranslation('settings');

  return 




{t('title')}
;
}

Bu yaklaşım, uygulamanın ilk açılış süresini (FCP - First Contentful Paint) önemli ölçüde iyileştirir. Büyük ölçekli projelerde, çeviri dosyalarının boyutunu küçültmek için gereksiz boşlukları temizleyen (minification) araçlar kullanmayı ve CDN üzerinden servis edilen statik dosyalarla cache mekanizmalarını devreye almayı unutmayın.

Çeviri Dosyalarında Bellek Yönetimi

• Namespace Kullanımı: Tüm metinleri tek bir translation.json yerine sayfa bazlı dosyalara bölün.
• Backend Entegrasyonu: i18next-http-backend ile dosyaları sunucudan dinamik olarak çekin.
• Caching: Tarayıcı önbelleğini (HTTP Cache) kullanarak çeviri dosyalarının tekrar tekrar indirilmesini engelleyin.

Sonuç

React ile i18next kullanarak çok dilli bir arayüz oluşturmak, uygulamanızın profesyonelliğini ve erişilebilirliğini artırır. Bu rehberde kurulumdan, bileşen kullanımına ve dil değiştirme mekanizmasına kadar temel adımları tamamladınız. Bir sonraki adım olarak, çevirilerinizi bir veritabanından veya bir içerik yönetim sisteminden (CMS) dinamik olarak çeken bir yapı kurmayı deneyebilirsiniz.

Sorumluluk Reddi: Bu rehberdeki kod örnekleri genel eğitim amaçlıdır. Üretim ortamında (production) kullanmadan önce güvenlik açıklarını (XSS, veri doğrulama) gözden geçirdiğinizden ve güncel kütüphane sürümlerini takip ettiğinizden emin olun.