Context Crawler: better-i18n ile Daha Akıllı Çeviriler için AI Destekli Web Sitesi ve Repo Analizi

better-i18n AI Bağlamını Ürününüzden Nasıl Oluşturur

Çoğu lokalizasyon iş akışı manuel bir adımla başlar: biri string'leri etiketler, dosyaları dışa aktarır ve hiçbir şeyin atlanmadığını umar. better-i18n farklı bir yaklaşım benimser. Context Crawler, iki güçlü analiz modunu — web sitesi tarama ve repo tarama — birleştirerek AI çevirilerini çok daha doğru kılan zengin bağlamı otomatik olarak oluşturur.

Sonuç, AI çevirmenin tek bir string'i çevirmeden önce markanızı, ürün kelime dağarcığınızı ve teknik stack'inizi anladığı bir iş akışıdır.

Web Sitesi Analizi: Firecrawl Destekli Marka Keşfi

Context Crawler'ın web sitesi analizi modu, sağladığınız herhangi bir URL'den içerikleri sistematik olarak taramak ve çıkarmak için Firecrawl API'sini kullanır. Bu basit bir HTML kazıma değildir — Firecrawl, kullanıcıların gerçekte gördüklerini yakalamak için JavaScript ile render edilen sayfaları, SPA'ları ve dinamik içerikleri işler.

Web Sitesi Analizi Nasıl Çalışır

1. Bir URL girin — Ürününüzün pazarlama sitesini, dokümantasyonunu veya herhangi bir web özelliğini girin. Tarayıcı, herkese açık olan herhangi bir URL'yi kabul eder.
2. Firecrawl çıkarımı — Firecrawl API sayfaları render eder, dahili bağlantıları takip eder ve başlıklar, gövde metni, navigasyon etiketleri, CTA'lar ve meta veriler dahil yapılandırılmış içeriği çıkarır.
3. Terminoloji tespiti — AI analizi, taranan tüm sayfalarda tekrarlanan terimleri, markalı dili, ürün adlarını, özellik adlarını ve alana özgü kelime dağarcığını tespit eder.
4. Aday önerisi — Tespit edilen terimler, önerilen tanımlar, bağlam notları ve frekans verileriyle birlikte sözlük adayları olarak önerilir. Her aday, bulunduğu kaynak URL'leri içerir.

Web Sitesi Analizi Neleri Yakalar

• Marka terminolojisi — Sitenizde tutarlı biçimde görünen ürün adları, özellik adları, fiyatlandırma katmanı etiketleri ve özgün terimler
• Navigasyon kalıpları — Ürününüzün kelime dağarcığını tanımlayan menü etiketleri, breadcrumb metni ve CTA dili
• Alan kelime dağarcığı — Ürününüzün kesin ve tutarlı çeviri gerektiren sektöre özgü terimleri
• Ton ve ses sinyalleri — İçeriğinizin resmi, samimi, teknik veya pazarlama odaklı olup olmadığı — AI'nın uygun register ile çeviri yapmasına yardımcı olan bağlam

Web Sitesi Analizi Kullanım Senaryoları

• Yeni proje kurulumu — Lokalizasyona başlamadan önce pazarlama sitenizi tarayarak haftalar yerine dakikalar içinde bir sözlük ve bağlam profili oluşturun
• Rakip analizi — Hedef pazarlardaki rakip siteleri tarayarak benzer kavramları nasıl çevirdiklerini anlayın; bu bilgi kendi sözlük kararlarınıza yol gösterir
• İçerik denetimi — Son sözlük güncellemesinden bu yana ortaya çıkan yeni terminolojiyi tespit etmek için periyodik olarak yeniden tarayın

Repo Analizi: Framework ve Terminoloji Tespiti

Context Crawler'ın repo analizi modu, GitHub deponuza bağlanır ve çeviriyle ilgili bağlamı çıkarmak için kod tabanınızın derinlemesine analizini gerçekleştirir.

Repo Analizi Nasıl Çalışır

1. Bir GitHub reposu bağlayın — Repo URL'sini girin. Tarayıcı, public repolara doğrudan erişir; private repolara ise GitHub entegrasyonunuz aracılığıyla erişir.
2. Framework tespiti — Analizör, teknik stack'inizi tespit eder: React, Next.js, Vue, Angular, Svelte, Flutter, React Native ve diğerleri. Bu, hangi i18n kalıplarına bakılacağını ve kodunuzun nasıl parse edileceğini belirler.
3. i18n kalıp tanıma — Tespit edilen framework'e göre analizör, mevcut çeviri fonksiyon çağrılarını (t(), useTranslations(), $t(), tr(), vb.) bulur ve projenizin çevirilerini nasıl yapılandırdığını haritalandırır.
4. Terminoloji çıkarımı — Analizör, sabit kodlanmış string'leri, component adlarını, route etiketlerini ve ürün kelime dağarcığınızı temsil eden diğer kullanıcıya yönelik metinleri tespit eder.
5. Bağlam profili oluşturma — Tüm bulgular; tespit edilen framework'leri, i18n kütüphane kullanımını, namespace yapısını ve terminoloji adaylarını içeren bir bağlam profilinde derlenir.

Repo Analizi Neleri Tespit Eder

• Framework ve i18n kütüphanesi — Stack'inizin otomatik tespiti, böylece AI çevirileri doğru biçimlendirme kurallarını kullanır (ICU MessageFormat, i18next interpolation, Flutter ARB, vb.)
• Namespace yapısı — Projenizin çeviri anahtarlarını nasıl düzenlediği, yeni çevirilerin aynı kalıpları izlemesi için
• Mevcut terminoloji — Kod tabanınızda zaten kullanılan terimler, sözlüğe nelerin eklenmesi gerektiğini belirlemeye yardımcı olur
• String kalıpları — Kullanıcıya yönelik string'lerinizdeki yaygın kalıplar (tarih formatları, sayı formatları, çoğullama yaklaşımları) çeviri kurallarını bilgilendirir

AST Tabanlı Anahtar Tespiti

Bağlam oluşturmanın ötesinde, CLI'nin scan komutu kaynak kodunuzu kırılgan regex eşlemesi yerine sözdizimi ağacı düzeyinde ayrıştırır. React JSX, useTranslations ve getTranslations kalıplarını doğal olarak anlar. Bu, <h1>Welcome back</h1> gibi kullanıcıya yönelik bir string ile className="flex items-center" gibi teknik bir string'i yanlış pozitifler olmadan ayırt edebildiği anlamına gelir.

Neler tespit edilir:

• Sabit kodlanmış JSX metni — t() çağrılarına sarılması gereken <h1>Hello</h1> gibi içerikler
• Sabit kodlanmış JSX attribute'ları — <img alt="Company logo" /> gibi kullanıcıya görünür attribute'lar
• Toast ve bildirim string'leri — toast.error("Something went wrong") gibi çağrılar
• Locale tabanlı üçlü mantık — Manuel locale yönetimini gösteren locale === 'en' ? 'Hi' : 'Hola' gibi kalıplar
• String değişkenleri — Kullanıcıya yönelik göründüğü düşünülen metin içeren değişkenler

Neler akıllıca yok sayılır:

• Tailwind ve CSS sınıf adları
• URL'ler, dosya yolları ve görsel kaynakları
• HTML entity'leri (&, ")
• SCREAMING_CASE biçimindeki teknik sabitler
• Sayılar ve metinsel olmayan değerler

better-i18n scan              # Mevcut dizini tara
better-i18n scan --dir ./src  # Belirli bir dizini tara
better-i18n scan --staged     # Yalnızca staged dosyalar (pre-commit hook'ları için)
better-i18n scan --ci         # Sorun bulunursa exit code 1
better-i18n scan --format json # Araçlar için JSON çıktı
better-i18n scan --verbose    # Tarama denetimiyle birlikte ayrıntılı çıktı

Namespace Çözümleme

Tarayıcı, hem client hem de server component'ler için namespace'leri otomatik olarak çözümlemek üzere lexical scope takibini kullanır. Bu önemlidir; çünkü tespit edilen anahtarların yalnızca anahtar adını değil, tam namespace yolunu içerdiği anlamına gelir.

Hook kullanan client component'ler için:

const t = useTranslations('hero');
return <h1>{t('title')}</h1>; // Şu şekilde tespit edilir: hero.title

Async fonksiyon kullanan server component'ler için:

const t = await getTranslations('welcome');
return <h1>{t('title')}</h1>; // Şu şekilde tespit edilir: welcome.title

Tarayıcı ayrıca nesne formunu (getTranslations({ locale, namespace: 'settings' })) ve namespace sağlanmadığı root kapsamlı çevirmenleri de işler. Değişkenler veya template literal'lar kullanan dinamik namespace'ler --verbose modunda raporlanır ve yanlış pozitifleri önlemek için metriklerden çıkarılır.

Analizden Sözlüğe: Tam Pipeline

Context Crawler'ın web sitesi ve repo analizi modları doğrudan Sözlük Yönetimi sistemine beslenir:

1. Tara — Firecrawl aracılığıyla web sitesi analizi marka terminolojisini çıkarır; repo analizi framework bağlamını ve mevcut terimleri tespit eder.
2. Öner — Tespit edilen terimler taslak statüsüyle sözlük adayları olarak önerilir.
3. İncele — Ekibiniz önerilen terimleri inceleyerek tanımları ve çevirileri gerektiği gibi düzenler.
4. Onayla — Onaylanan terimler AI çevirisinde ve inceleme editöründe hemen uygulanır.
5. Senkronize et — Onaylanan terimler, sağlayıcı düzeyinde uygulanması için DeepL ile senkronize edilebilir.

Bu pipeline, "sözlüğümüz yok" durumundan "AI çevirilerimiz 200 marka terimini uygular" durumuna tek bir öğleden sonrada geçebileceğiniz anlamına gelir.

Sync: Yerel ile Cloud Karşılaştırması

sync komutu, kodunuzun kullandığı ile better-i18n'de mevcut olanlar arasındaki boşluğu kapatır. Kod tabanınızı scan ile aynı şekilde tarar, ardından anahtar kümelerini karşılaştırmak için better-i18n API'sini sorgular.

Çıktı, net bir karşılaştırma raporu sunar:

• Remote'ta Eksik — Kodunuzda başvurulan ancak henüz better-i18n'e yüklenmemiş anahtarlar. Bunlar, kullanıcılarınızın çevrilmemiş görebileceği string'lerdir.
• Kodda Kullanılmayan — better-i18n'de mevcut olan ancak kaynak kodunuzda artık başvurulmayan anahtarlar. Bunlar temizleme için adaylardır.

better-i18n sync              # Gruplandırılmış ağaç çıktısı
better-i18n sync --summary    # Yalnızca üst düzey kapsam metrikleri
better-i18n sync --format json # CI otomasyonu için JSON çıktı
better-i18n sync -d ./src     # Belirli bir dizini tara

Ağaç çıktısı, anahtarları namespace'e göre gruplandırarak uygulamanızın hangi bölümlerinde eksiklikler olduğunu görmeyi kolaylaştırır. --verbose bayrağı, değişmez kontroller, kapsam özetleri ve belirli anahtar probları dahil ayrıntılı bir denetim günlüğü sağlar.

Kapsam Metrikleri

Sync komutu yüzde tabanlı kapsam metrikleri sağlar:

• Yerel'den Remote'a kapsam: Kodunuzda kullanılan anahtarların yüzde kaçı better-i18n'de mevcut
• Remote kullanımı: better-i18n'deki anahtarların yüzde kaçı kodunuzda gerçekten kullanılıyor

Bu rakamlar, ekibinize herhangi bir zamanda çeviri durumunun net bir resmini sunar. Bunları terminal çıktısında görüntüleyebilir veya özel dashboard'lar ve raporlama için JSON çıktısından çekebilirsiniz.

CI Entegrasyonu

Hem scan hem de sync, otomatik pipeline'larda çalışacak şekilde tasarlanmıştır. Sabit kodlanmış string'ler tespit edildiğinde build'leri başarısız kılmak için scan ile --ci kullanın; eksik anahtar sayısına göre deploy'ları engellemek için sync çıktısını jq ile pipe edin.

# GitHub Actions örneği
name: i18n Check
on: [push, pull_request]
jobs:
  lint:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - run: npx @better-i18n/cli scan --ci
      - run: |
          npx @better-i18n/cli sync --format json \
            | jq -e '.comparison.missingCount == 0' > /dev/null || exit 1

Pre-commit hook'lar için geri bildirimi hızlı tutmak amacıyla yalnızca staged dosyaları tarayın:

npx husky init
echo "npx @better-i18n/cli scan --staged --ci" > .husky/pre-commit

Neler Yapılmaz

Beklentileri netleştirmek için:

• Görsel bağlam yakalama yok — CLI, render edilen UI değil kod düzeyinde çalışır. String'lerin nerede göründüğüne dair ekran görüntüsü veya görsel önizleme yoktur.
• Gerçek zamanlı izleme yok — scan ve sync, talep üzerine veya CI pipeline'larında çalıştırılır; arka plan izleyicileri veya dosya sistemi gözlemcileri değildir.
• Eski çeviri tespiti yok — sync komutu eksik ve kullanılmayan anahtarları gösterir, ancak mevcut bir çevirinin kaynak metin değişikliğine göre güncelliğini yitirip yitirmediğini tespit etmez.

Başlarken

CLI'yi yükleyin ve bir dakika içinde ilk taramanızı çalıştırın:

npm install -g @better-i18n/cli
better-i18n scan --dir ./src

Ardından better-i18n projenize bağlanın ve cloud ile karşılaştırın:

better-i18n sync

Web sitesi analizine başlamak için proje dashboard'unuzdaki AI Bağlamı bölümünü ziyaret edin, bir URL girin ve Firecrawl'ın marka terminolojinizi çıkarmasına izin verin. Repo analizi için GitHub reponuzu bağlayın ve analizörün framework'ünüzü ve mevcut terminolojinizi tespit etmesine izin verin.

Yapılandırma seçenekleri, tespit kuralları ve gelişmiş kullanım için tam CLI dokümantasyonuna bakın.

Çeviri bağlamınızı ve terminoloji keşfinizi otomatikleştirmeye hazır mısınız? Hesabınızı oluşturun ve ilk projenizi bağlayın — ya da tarayıcının keşfettiği terimleri Sözlük Yönetimi sisteminin nasıl uyguladığını öğrenin.