JavaScript ile Tarayıcı Tabanlı Bir Sayfa İçi Yazı Çeviri Aracı Nasıl Yapılır?

Modern web uygulamalarında kullanıcı deneyimini artırmanın en etkili yollarından biri, içeriğin kullanıcı tarafından anında çevrilebilmesidir. JavaScript ile tarayıcı tabanlı bir sayfa içi yazı çeviri aracı nasıl yapılır sorusu, özellikle çok dilli platformlar geliştiren yazılımcılar için kritik bir öneme sahiptir. Bu rehberde, herhangi bir sunucu tarafı işlemine ihtiyaç duymadan, tarayıcı üzerinde çalışan ve DOM (Document Object Model) elemanlarını manipüle ederek metinleri dönüştüren bir sistemin temellerini öğreneceksiniz.

Bu eğitim, orta seviye JavaScript bilgisine sahip yazılımcılar için hazırlanmıştır. Eğitim sonunda, sayfadaki metin düğümlerini tespit eden, bunları bir sözlük yapısı ile eşleştiren ve kullanıcı etkileşimiyle dili değiştiren modüler bir yapı kurmuş olacaksınız. 2026 standartlarına uygun olarak, modern ES6+ söz dizimi ve performans odaklı DOM manipülasyon tekniklerini kullanacağız.

Gereksinimler ve Ön Hazırlık

Bu projeyi geliştirmek için ekstra bir kütüphane kurulumuna ihtiyacınız yoktur. Tarayıcı tabanlı bir çözüm olduğu için sadece modern bir kod editörü (VS Code gibi) ve güncel bir tarayıcı yeterlidir. Ancak, projenin ölçeklenebilir olması için aşağıdaki temel prensiplere hakim olmanız beklenir:

• ES6+ JavaScript: Arrow functions, destructuring ve template literals kullanımı.
• DOM API: querySelectorAll, childNodes ve textContent özellikleri.
• JSON: Çeviri verilerini saklamak için kullanılacak veri yapısı.

Projenin temelinde, sayfadaki metinleri "data-translate" gibi özel bir öznitelik (attribute) ile işaretlemek veya doğrudan metin düğümlerini taramak yer alır. Biz bu rehberde, daha esnek bir yaklaşım olan "data-key" özniteliklerini kullanacağız.

Adım 1: Çeviri Sözlüğünü Oluşturma

Çeviri aracımızın kalbi, diller arasındaki eşleşmeleri tutan bir JavaScript nesnesidir. Bu nesne, uygulamanızın desteklediği tüm dilleri ve karşılıklarını bir JSON formatında barındırır.

const translations = {
  tr: {
    "welcome_message": "Hoş geldiniz!",
    "submit_button": "Gönder"
  },
  en: {
    "welcome_message": "Welcome!",
    "submit_button": "Submit"
  }
};

Bu yapı, çevirileri merkezi bir noktadan yönetmenizi sağlar. Uygulama büyüdükçe bu nesneyi harici bir JSON dosyasından fetch metodu ile çekebilirsiniz.

Adım 2: Çevrilebilir Alanları İşaretleme

HTML içerisinde hangi metinlerin çevrileceğini belirlemek için özel bir öznitelik kullanmalıyız. Bu, JavaScript'in sayfayı tararken hangi elemanları değiştireceğini anlamasını sağlar.

Hoş geldiniz!
Gönder

data-key kullanımı, metin içeriğini HTML'den ayırarak kodunuzun daha temiz ve yönetilebilir olmasını sağlar. Bu yöntem, SEO açısından da metinlerin tarayıcılar tarafından kolayca indekslenmesine olanak tanır.

Adım 3: Çeviri Motorunu Yazma

Şimdi, seçilen dile göre sayfadaki tüm data-key elemanlarını güncelleyen fonksiyonumuzu yazalım. Bu fonksiyon, DOM üzerinde bir döngü kurarak metin içeriklerini günceller.

function translatePage(language) {
  const elements = document.querySelectorAll('[data-key]');
  elements.forEach(element => {
    const key = element.getAttribute('data-key');
    if (translations[language] && translations[language][key]) {
      element.textContent = translations[language][key];
    }
  });
}

Bu fonksiyon, sayfadaki tüm çevrilebilir öğeleri bulur ve ilgili dildeki karşılığı ile değiştirir. Eğer bir anahtar bulunamazsa, hata oluşmaması için basit bir kontrol mekanizması ekledik.

Adım 4: Kullanıcı Etkileşimi ve Dil Değiştirici

Kullanıcının dili değiştirebilmesi için bir arayüz elemanına ihtiyacımız var. Bir select veya buton grubu kullanarak translatePage fonksiyonunu tetikleyebiliriz.

document.getElementById('lang-selector').addEventListener('change', (event) => {
  const selectedLang = event.target.value;
  translatePage(selectedLang);
  localStorage.setItem('preferred_lang', selectedLang);
});

Burada localStorage kullanarak kullanıcının seçimini tarayıcıda saklıyoruz. Böylece kullanıcı sayfayı yenilediğinde seçtiği dil korunmuş olur.

Performans ve Yöntem Karşılaştırması

Sayfa içi çeviri yaparken farklı yöntemler mevcuttur. Aşağıdaki tablo, bu yöntemlerin avantaj ve dezavantajlarını özetlemektedir.

Kritik Güvenlik ve Uyarılar

Güvenlik Uyarısı: Sayfa içi çeviri yaparken kesinlikle innerHTML kullanmaktan kaçının. Bunun yerine her zaman textContent kullanın. innerHTML kullanmak, kullanıcı tarafından manipüle edilebilecek bir metin içeriğinin XSS (Cross-Site Scripting) saldırılarına kapı aralamasına neden olabilir.

Sıkça Sorulan Sorular

Çeviri aracı SEO'yu nasıl etkiler?

Bu yöntem istemci tarafında (client-side) çalıştığı için, arama motorları başlangıçta HTML'deki varsayılan dili görür. Eğer çok dilli SEO kritikse, sunucu tarafı render (SSR) yöntemlerini tercih etmelisiniz.

Çok fazla metin olduğunda performans düşer mi?

Çok fazla metin olduğunda querySelectorAll yerine DocumentFragment veya optimize edilmiş bir sanal DOM yapısı kullanmak performansı artıracaktır.

Kullanıcı sayfayı yenileyince çeviri kaybolur mu?

Yukarıdaki örnekte localStorage kullanarak kullanıcının tercihini tarayıcıda sakladık, bu sayede sayfa yenilense bile çeviri korunur.

Dinamik olarak eklenen içerikleri nasıl çeviririm?

Dinamik içerikler için MutationObserver API'sini kullanarak yeni eklenen DOM elemanlarını izleyebilir ve çeviri fonksiyonunu bu elemanlar için tetikleyebilirsiniz.

Bu yöntemle tüm dilleri destekleyebilir miyim?

Evet, translations nesnesini bir API'den JSON olarak çekerseniz, sınırsız dil desteği ekleyebilirsiniz.

İleri Seviye: Harici JSON Dosyaları ile Dinamik Çeviri Yönetimi

Küçük projelerde çeviri sözlüğünü JavaScript objesi olarak tutmak pratik olsa da, ölçeklenebilir uygulamalarda çevirileri harici bir .json dosyasında tutmak daha profesyonel bir yaklaşımdır. Bu yöntem, çeviri metinlerini koddan ayırarak bakım sürecini kolaylaştırır.

Asenkron Veri Çekme ve Uygulama

Çeviri dosyasını fetch API'si ile çekerek uygulama başladığında belleğe yükleyebiliriz. Aşağıdaki örnekte, kullanıcının tarayıcı dili algılanarak ilgili JSON dosyasının dinamik olarak yüklenmesi gösterilmiştir.

async function loadTranslations(lang) {
    try {
        const response = await fetch(`./locales/${lang}.json`);
        if (!response.ok) throw new Error('Dil dosyası bulunamadı.');
        return await response.json();
    } catch (error) {
        console.error("Çeviri yükleme hatası:", error);
        return null;
    }
}

// Kullanım:
const userLang = navigator.language.split('-')[0] || 'tr';
loadTranslations(userLang).then(data => {
    if (data) {
        applyTranslations(data);
    }
});

Performans Optimizasyonu ve Önbellekleme Stratejileri

Sayfa içi çeviri araçlarında en büyük darboğaz, DOM ağacının sürekli taranmasıdır. Büyük sayfalarda her dil değişiminde tüm sayfayı taramak yerine, sadece çevrilebilir alanları bir Map yapısında tutmak performansı ciddi oranda artırır.

DOM Seçicilerini Önbelleğe Alma (Caching)

Sayfa yüklendiğinde çevrilebilir tüm öğeleri bir kez seçip dizine eklemek, sonraki dil değişimlerinde DOM'u tekrar tarama maliyetini ortadan kaldırır.

const translationCache = new Map();

function initializeCache() {
    const elements = document.querySelectorAll('[data-i18n]');
    elements.forEach(el => {
        translationCache.set(el, el.getAttribute('data-i18n'));
    });
}

function updateUI(translations) {
    translationCache.forEach((key, element) => {
        if (translations[key]) {
            element.textContent = translations[key];
        }
    });
}

Hata Ayıklama (Debugging) İpuçları

Çeviri aracınızı geliştirirken karşılaşabileceğiniz yaygın sorunlar ve çözüm yolları:

• Eksik Anahtarlar: JSON dosyanızda bulunmayan bir anahtar için varsayılan dili (fallback) her zaman tanımlayın.
• XSS Riski: Çevirileri innerHTML ile değil, her zaman textContent ile atayın. Bu, çeviri dosyasına sızabilecek kötü niyetli scriptlerin çalışmasını engeller.
• Layout Shift: Metin uzunlukları diller arasında farklılık gösterebilir (örneğin Almanca, Türkçe'den daha uzun olabilir). CSS tarafında min-height veya text-overflow: ellipsis kullanarak arayüzün bozulmasını engelleyin.

Profesyonel İpucu: Eğer uygulamanız çok fazla metin içeriyorsa, çevirileri sayfa sayfa (lazy-loading) yüklemek, ilk açılış hızını (LCP - Largest Contentful Paint) olumlu etkileyecektir.

Sonuç

JavaScript ile tarayıcı tabanlı bir sayfa içi çeviri aracı yapmak, kullanıcı deneyimini iyileştiren ve uygulamanıza profesyonel bir dokunuş katan etkili bir yöntemdir. Bu rehberde öğrendiğiniz DOM manipülasyonu ve veri yönetimi tekniklerini, daha büyük projelerde bir "i18n" (internationalization) kütüphanesi ile birleştirerek daha karmaşık sistemler kurabilirsiniz.

Yasal Uyarı: Bu makalede paylaşılan kod örnekleri eğitim amaçlıdır. Uygulamanızın canlı ortamdaki güvenlik açıklarından (XSS, veri sızıntısı vb.) geliştirici sorumludur. Üretim ortamına geçmeden önce kodunuzu güvenlik testlerinden geçirin.

Bir sonraki adım olarak, çevirileri bir JSON dosyasından asenkron olarak çekmeyi ve kullanıcının tarayıcı dilini (navigator.language) otomatik algılayarak varsayılan dili atamayı deneyebilirsiniz.