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 (LTS) kurulu olduğundan emin olun. React projenizin oluşturulmuş olması gerekmektedir. Eğer henüz bir projeniz yoksa, npx create-react-app veya vite kullanarak hızlıca bir başlangıç yapabilirsiniz.

Projenize gerekli kütüphaneleri dahil etmek için terminalinizde aşağıdaki komutu çalıştırın:

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

Bu paketlerin ne işe yaradığını kısaca özetleyelim: i18next ana çeviri motorudur. react-i18next, React bileşenleri ile bu motoru bağlar. i18next-browser-languagedetector kullanıcının tarayıcı dilini otomatik algılar. i18next-http-backend ise çeviri dosyalarını dışarıdan (public klasöründen) yüklemenize olanak tanır.

Adım Adım i18next Yapılandırması

Çeviri yönetimini merkezi bir noktadan yönetmek için src/i18n.js adında bir dosya oluşturacağız. Bu dosya, uygulamanızın dil ayarlarını ve çeviri kaynaklarını yapılandıran ana merkez olacaktır.

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', 'de'],
    fallbackLng: 'en',
    detection: {
      order: ['cookie', 'htmlTag', 'localStorage', 'path', 'subdomain'],
      caches: ['cookie'],
    },
    backend: {
      loadPath: '/assets/locales/{{lng}}/translation.json',
    },
  });

export default i18n;

Burada supportedLngs ile desteklediğimiz dilleri, fallbackLng ile kullanıcının dili tanımlı değilse varsayılan olarak hangi dilin geleceğini belirliyoruz. backend kısmındaki loadPath ise çeviri dosyalarımızın public/assets/locales dizini altında, dil kodlarına göre ayrılmış klasörlerde bulunacağını belirtir.

Çeviri Dosyalarının Hazırlanması

React projenizin public klasörü içerisinde assets/locales dizinini oluşturun. Her dil için bir klasör açarak içerisine translation.json dosyasını ekleyin. Örneğin, İngilizce ve Türkçe için şu yapıyı kurun:

// public/assets/locales/en/translation.json
{
  "welcome": "Welcome to our application",
  "description": "This is a multilingual React app."
}

// public/assets/locales/tr/translation.json
{
  "welcome": "Uygulamamıza hoş geldiniz",
  "description": "Bu çok dilli bir React uygulamasıdır."
}

Bu JSON dosyaları, uygulamanızdaki anahtar-değer çiftlerini tutar. Anahtar (key) her dilde aynı kalmalı, değer (value) ise ilgili dile göre çevrilmelidir. Bu yöntem, kodunuzu değiştirmeden sadece JSON dosyalarını güncelleyerek yeni diller eklemenize olanak tanır.

Bileşenlerde Çeviri Kullanımı

Artık kurulum tamamlandı. Bileşenlerinizde çevirileri kullanmak için useTranslation hook'unu kullanacağız. Bu hook, çeviri fonksiyonunu ve mevcut dil bilgilerini bize döndürür.

import React from 'react';
import { useTranslation } from 'react-i18next';

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

  return (
    

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

export default App;

t fonksiyonu, verdiğiniz anahtarı JSON dosyalarından arar ve karşılığını ekrana basar. Eğer anahtar bulunamazsa, varsayılan olarak anahtarın kendisini gösterir.

Dil Değiştirme Fonksiyonelliği

Kullanıcının dili değiştirebilmesi için i18n.changeLanguage metodunu kullanırız. Basit bir dil seçici bileşeni şu şekilde oluşturulabilir:

import React from 'react';
import { useTranslation } from 'react-i18next';

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

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

  return (
    

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

export default LanguageSwitcher;

Bu bileşeni uygulamanızın header kısmına ekleyerek kullanıcıya dil seçme imkanı sunabilirsiniz. i18n.changeLanguage metodu, arka planda gerekli çeviri dosyalarını otomatik olarak yükler ve arayüzü günceller.

Çeviri Yöntemlerinin Karşılaştırılması

Güvenlik Uyarısı: Çeviri dosyalarınızda asla hassas verileri (API anahtarları, kullanıcı şifreleri vb.) tutmayın. Bu dosyalar istemci tarafında (browser) herkes tarafından görüntülenebilir. Ayrıca, çeviri metinlerinde HTML etiketi kullanıyorsanız, XSS saldırılarına karşı dikkatli olun ve react-i18next'in sunduğu güvenli render yöntemlerini tercih edin.

Sıkça Sorulan Sorular

Çeviri dosyalarım neden yüklenmiyor?

Genellikle public klasöründeki yolun yanlış tanımlanmasından kaynaklanır. loadPath ayarınızın, dosyaların bulunduğu fiziksel konumla eşleştiğinden emin olun.

Dinamik değişkenleri çeviriye nasıl eklerim?

t('hello', { name: 'Ahmet' }) şeklinde kullanabilir ve JSON dosyanızda "hello": "Merhaba {{name}}" şeklinde tanımlayabilirsiniz.

SEO açısından çok dilli uygulamalar nasıl etkilenir?

Google, dil değiştirme seçeneklerinin belirgin olmasını ve hreflang etiketlerinin doğru kullanılmasını önerir. React tarafında react-helmet kullanarak meta etiketlerini dinamik yönetebilirsiniz.

Performans kaybı yaşar mıyım?

i18next-http-backend ile çeviriler sadece ihtiyaç duyulduğunda yüklenir (lazy loading). Bu, uygulamanın başlangıç hızını olumlu etkiler.

Sağdan sola (RTL) diller (Arapça gibi) nasıl desteklenir?

i18next ile dilin yönünü kontrol edebilir ve CSS tarafında direction: rtl özelliğini dinamik olarak uygulayabilirsiniz.

Gelişmiş Senaryo: Trans Bileşeni ile Karmaşık HTML Yapılarını Yönetme

Çeviri dosyalarınızda sadece düz metinler değil, bazen bağlantılar, kalın yazılmış kelimeler veya liste öğeleri gibi HTML etiketleri içeren yapılar kullanmanız gerekebilir. i18next'in sunduğu Trans bileşeni, bu tür karmaşık metinleri güvenli ve yönetilebilir bir şekilde çevirmenize olanak tanır.

Örneğin, bir kullanıcı sözleşmesini onaylama metninde "Kullanım Koşulları" ifadesini bir linke dönüştürmek istediğinizde şu yöntemi izleyebilirsiniz:

import { Trans } from 'react-i18next';

const TermsComponent = () => {
  return (
    

      
        Devam ederek Kullanım Koşullarını kabul etmiş olursunuz.
      
    
  );
};

Çeviri dosyanızda (JSON) ise bu yapıyı şu şekilde tanımlarsınız:

{
  "terms_agreement": "Devam ederek Kullanım Koşullarını kabul etmiş olursunuz."
}

Buradaki etiketi, Trans bileşeninin içindeki ikinci çocuk öğeyi (yani etiketini) temsil eder. Bu yöntem, çeviri dosyalarınızın okunabilirliğini artırırken, kodunuzun içinde hard-coded metin bırakmanızı engeller.

import { render } from '@testing-library/react';
import { I18nextProvider } from 'react-i18next';
import i18n from './i18n-test-config'; // Test konfigürasyonunuz

test('hoş geldin mesajı doğru dilde render edilmeli', () => {
  i18n.changeLanguage('tr');
  const { getByText } = render(
    
      
    
  );
  expect(getByText(/Hoş geldiniz/i)).toBeInTheDocument();
});