Lingo.dev Nasıl Kullanılır: Başlangıç Rehberi

Uluslararası kitlelere ulaşmak için çok dilli uygulamalar oluşturmak artık zorunlu hale geldi. Ancak, geleneksel uluslararasılaştırma (i18n) yaklaşımları genellikle önemli kod yeniden düzenlemeleri, karmaşık yapılandırmalar ve sürekli bakım yükü gerektirir. İşte tam da bu noktada Lingo.dev yerelleştirme sürecinde devrim yaratıyor.

Lingo.dev, geliştiricilerin çok dilli uygulamalara yaklaşımını dönüştüren açık kaynaklı, yapay zeka destekli bir uluslararasılaştırma araç setidir. Gelişmiş dil modellerinden ve akıllı otomasyondan yararlanarak, geleneksel yerelleştirme zorluklarını ortadan kaldırır ve tüm uygulamaları minimum çabayla ve maksimum doğrulukla çevirmeyi mümkün kılar.

Bu kapsamlı eğitim, ilk kurulumdan gelişmiş uygulama stratejilerine kadar tüm Lingo.dev ekosistemi boyunca size rehberlik edecektir. İster basit bir web sitesi, ister karmaşık bir kurumsal uygulama geliştiriyor olun, yapay zeka destekli yerelleştirmenin gücünü kullanarak gerçekten küresel yazılımlar oluşturmayı öğreneceksiniz.

Lingo.dev'e Başlarken

Ön Koşullar ve Ortam Kurulumu

Lingo.dev yolculuğunuza başlamadan önce, geliştirme ortamınızın şu gereksinimleri karşıladığından emin olun:

1. Node.js: En iyi uyumluluk için Sürüm 16.0 veya üstü gereklidir
2. Paket Yöneticisi: npm, yarn veya pnpm (monorepo kurulumları için pnpm önerilir)
3. React Uygulaması: Derleyici kullanımı için mevcut bir React projeniz olması gerekir
4. API Anahtarı: Birçok özellik çevrimdışı çalışsa da, gelişmiş yapay zeka modelleri bir API anahtarı gerektirir

Kurulum Süreci

Lingo.dev'in güzelliği, basit kurulum sürecinde yatar. Çoğu kullanım durumu için tek bir komutla başlayabilirsiniz:

npm install lingo.dev

Bu komut, dört bileşenin tamamını içeren çekirdek paketi yükler. Özel ihtiyaçlarınıza bağlı olarak ek paketler de yüklemek isteyebilirsiniz:

# TypeScript desteği için
npm install --save-dev @types/lingo.dev

# Belirli framework entegrasyonları için
npm install lingo.dev-next  # Next.js'e özel özellikler
npm install lingo.dev-vite  # Vite'a özel özellikler

İlk Yapılandırma

Kurulumdan sonra, yerelleştirme ayarlarınızı tanımlamak için bir yapılandırma dosyası oluşturun. Yapılandırma yaklaşımı, kullandığınız bileşene göre değişir, ancak temel kavramlar tutarlıdır.

Derleyici kullanan tipik bir React uygulaması için, proje kök dizininizde bir lingo.config.js dosyası oluşturun:

module.exports = {
  // Kaynak dilinizi tanımlayın
  sourceLocale: "en",

  // Çeviri için hedef dilleri belirtin
  targetLocales: ["es", "fr", "de", "ja", "zh"],

  // Çeviri için yapay zeka modellerini yapılandırın
  models: {
    // Dil çiftleri için belirli modeller kullanın
    "en:es": "gpt-4",
    "en:fr": "claude-3",
    // Diğer tüm çiftler için varsayılan model
    "*:*": "groq:mistral-saba-24b",
  },

  // Gelişmiş seçenekler
  caching: {
    enabled: true,
    directory: ".lingo-cache",
  },

  // Kalite güvence ayarları
  validation: {
    checkPlurals: true,
    validateVariables: true,
    ensureCompleteness: true,
  },
};

Derleyiciyi Uygulama

Next.js Entegrasyonu

Next.js uygulamaları için Derleyici entegrasyonu oldukça zariftir. next.config.js veya next.config.ts dosyanızı değiştirin:

import lingoCompiler from "lingo.dev/compiler";

const nextConfig = {
  // Mevcut Next.js yapılandırmanız
  reactStrictMode: true,
  images: {
    domains: ["example.com"],
  },
};

// Yapılandırmanızı Lingo derleyicisi ile sarmalayın
export default lingoCompiler.next({
  sourceLocale: "en",
  targetLocales: ["es", "fr", "de", "ja"],
  models: {
    "*:*": "groq:mistral-saba-24b",
  },
  useDirective: true,
})(nextConfig);

Derleme Sürecini Anlama

Bu yapılandırma ile next build komutunu çalıştırdığınızda, Derleyici birkaç gelişmiş işlem gerçekleştirir:

1. Statik Analiz: Tüm React bileşen ağacınızı ayrıştırır ve tüm metin içeriğini tanımlar
2. Bağlam Çıkarma: Yapay zeka, doğru çeviri için bağlamı anlamak üzere çevredeki kodu analiz eder
3. Çeviri Üretimi: Tanımlanan her dize belirtilen yapay zeka modeli kullanılarak çevrilir
4. Paket Oluşturma: Her hedef dil için ayrı paketler oluşturulur
5. Optimizasyon: Çeviriler tekrar edilmez ve minimum paket boyutu için optimize edilir

Çeviriye Hazır Bileşenler Yazma

Derleyici özel bir sözdizimi gerektirmese de, belirli kalıpları takip etmek en iyi çeviri kalitesini sağlar:

// İyi: Açık, tam cümleler
function WelcomeMessage() {
  return (
    <div>
      <h1>Platformumuza Hoş Geldiniz</h1>
      <p>Özelliklerimizi keşfederek yolculuğunuza başlayın.</p>
    </div>
  );
}

// Daha iyi: Bağlam için anlamsal HTML kullanma
function ProductCard({ product }) {
  return (
    <article>
      <h2>{product.name}</h2>
      <p className="price">${product.price}</p>
      <button>Sepete Ekle</button>
    </article>
  );
}

// En iyisi: Erişilebilirlik için aria-etiketleri dahil etme
function Navigation() {
  return (
    <nav aria-label="Ana gezinme">
      <a href="/home">Ana Sayfa</a>
      <a href="/products">Ürünler</a>
      <a href="/about">Hakkımızda</a>
    </nav>
  );
}

CLI'ya Hakim Olma

Temel Çeviri Komutları

CLI, uygulama kodunuzun dışındaki dosyaları çevirmek için güçlü yetenekler sağlar. İşte etkili bir şekilde nasıl kullanabileceğiniz:

# Tek bir dosyayı çevir
npx lingo.dev translate data/content.json --to es,fr,de

# Tüm bir dizini çevir
npx lingo.dev translate content/ --to ja --recursive

# Belirli bir modelle çevir
npx lingo.dev translate README.md --to zh --model gpt-4

Gelişmiş CLI Özellikleri

CLI'nın akıllı önbellekleme sistemi, yalnızca değişen içeriği çevirerek verimlilik sağlar:

# İlk çalıştırma: her şeyi çevirir
npx lingo.dev run

# Sonraki çalıştırmalar: yalnızca değişiklikleri çevirir
npx lingo.dev run --cache-dir .lingo-cache

Yapılandırma dosyalarını kullanarak çeviri iş akışları da oluşturabilirsiniz:

# .lingo-cli.yml
version: 1
projects:
  - name: documentation
    source: ./docs
    include: "**/*.md"
    exclude: "**/drafts/**"
    targetLocales: [es, fr, de, ja]

  - name: content
    source: ./content
    include: "**/*.json"
    targetLocales: [es, fr, de, ja, zh, ko]
    model: claude-3

Farklı Dosya Türlerini Yönetme

CLI çeşitli dosya formatlarını akıllıca yönetir:

JSON Dosyaları: Değerleri çevirirken yapıyı korur

// Orijinal
{
  "welcome": "Hoş Geldiniz",
  "features": {
    "title": "Özelliklerimiz",
    "description": "Sunduklarımızı keşfedin"
  }
}

// Çevrilmiş (İspanyolca)
{
  "welcome": "Bienvenido",
  "features": {
    "title": "Nuestras Características",
    "description": "Descubre lo que ofrecemos"
  }
}

Markdown Dosyaları: İçeriği çevirirken biçimlendirmeyi korur

# Orijinal
## Başlarken
Başlamak için şu adımları izleyin.

# Çevrilmiş (Fransızca)
## Commencer
Suivez ces étapes pour commencer.

CI/CD Entegrasyonunu Kurma

GitHub Actions Yapılandırması

GitHub Actions ile yerelleştirme iş akışınızı otomatikleştirin:

name: Otomatik Yerelleştirme
on:
  push:
    branches: [main]
    paths:
      - "src/**"
      - "content/**"
      - "i18n.json"

jobs:
  localize:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          token: ${{ secrets.GITHUB_TOKEN }}

      - uses: actions/setup-node@v4
        with:
          node-version: "18"

      - uses: lingodotdev/lingo.dev@main
        with:
          api-key: ${{ secrets.LINGODOTDEV_API_KEY }}
          source-locale: en
          target-locales: es,fr,de,ja,zh

      - name: Çevirileri kaydet
        run: |
          git config --local user.email "action@github.com"
          git config --local user.name "GitHub Action"
          git add .
          git diff --staged --quiet || git commit -m "Çevirileri güncelle"
          git push

Gelişmiş CI/CD Stratejileri

Daha büyük projeler için gelişmiş iş akışları uygulayın:

name: Çeviri İnceleme Süreci
on:
  pull_request:
    types: [opened, synchronize]

jobs:
  translate-pr:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Değişen dosyaları tespit et
        id: changes
        run: |
          echo "files=$(git diff --name-only ${{ github.event.before }} ${{ github.sha }})" >> $GITHUB_OUTPUT

      - uses: lingodotdev/lingo.dev@main
        with:
          api-key: ${{ secrets.LINGODOTDEV_API_KEY }}
          files: ${{ steps.changes.outputs.files }}
          create-pr: true
          pr-title: "PR #${{ github.event.number }} için çeviriler"

SDK'dan Yararlanma

Gerçek Zamanlı Çeviri Uygulaması

SDK, çalışma zamanı çevirisi gerektiren dinamik içeriği işleme konusunda üstündür:

import { LingoDotDevEngine } from "lingo.dev/sdk";

// Motoru başlat
const translator = new LingoDotDevEngine({
  apiKey: process.env.LINGODOTDEV_API_KEY,
  defaultModel: "groq:mistral-saba-24b",
  caching: {
    enabled: true,
    ttl: 3600, // 1 saat önbelleğe al
  },
});

// Kullanıcı tarafından oluşturulan içeriği çevir
async function translateUserComment(comment, targetLanguage) {
  try {
    const translated = await translator.translate(comment, {
      sourceLocale: "auto", // Kaynak dili otomatik algıla
      targetLocale: targetLanguage,
      context: "sosyal medyadaki kullanıcı yorumu",
    });

    return translated;
  } catch (error) {
    console.error("Çeviri başarısız:", error);
    return comment; // Orijinale geri dön
  }
}

// Verimlilik için toplu çeviri
async function translateMultipleItems(items, targetLanguage) {
  const translations = await translator.translateBatch(items, {
    sourceLocale: "en",
    targetLocale: targetLanguage,
    preserveFormatting: true,
  });

  return translations;
}

Gelişmiş SDK Kalıpları

Karmaşık uygulamalar için gelişmiş çeviri kalıpları uygulayın:

// Bağlama duyarlı çeviri
class ContextualTranslator {
  constructor(apiKey) {
    this.engine = new LingoDotDevEngine({ apiKey });
    this.contextCache = new Map();
  }

  async translateWithContext(text, metadata) {
    const context = this.buildContext(metadata);

    return await this.engine.translate(text, {
      sourceLocale: metadata.sourceLanguage || "en",
      targetLocale: metadata.targetLanguage,
      context: context,
      tone: metadata.tone || "neutral",
      formality: metadata.formality || "casual",
    });
  }

  buildContext(metadata) {
    return `
      Alan: ${metadata.domain || "genel"}
      Kullanıcı Türü: ${metadata.userType || "tüketici"}
      Platform: ${metadata.platform || "web"}
      Konu: ${metadata.subject || "genel içerik"}
    `;
  }
}

// Kullanım
const translator = new ContextualTranslator(apiKey);
const translated = await translator.translateWithContext(
  "En son özelliklerimize göz atın!",
  {
    targetLanguage: "ja",
    domain: "teknoloji",
    userType: "geliştirici",
    formality: "profesyonel",
  }
);

En İyi Uygulamalar ve Optimizasyon

Performans Optimizasyonu

1. Akıllı Önbellek Uygulayın: API çağrılarını en aza indirmek için çevirileri birden çok düzeyde önbelleğe alın
2. Toplu İşlemler Kullanın: Birden çok çeviriyi tek istekle gruplandırın
3. CDN'den Yararlanın: Çevrilmiş statik varlıkları uç konumlardan sunun
4. Aşamalı Yükleme Uygulayın: Önce görünür içerik için çevirileri yükleyin

Kalite Güvencesi

Sistematik doğrulama yoluyla çeviri kalitesini sağlayın:

// Çeviri doğrulama ara yazılımı
function validateTranslation(original, translated, locale) {
  const checks = {
    // Değişkenlerin korunduğundan emin olun
    variablesPreserved: () => {
      const originalVars = original.match(/\{\{.*?\}\}/g) || [];
      const translatedVars = translated.match(/\{\{.*?\}\}/g) || [];
      return originalVars.length === translatedVars.length;
    },

    // Boş çevirileri kontrol edin
    notEmpty: () => translated.trim().length > 0,

    // HTML korumasını doğrulayın
    htmlPreserved: () => {
      const originalTags = original.match(/<[^>]+>/g) || [];
      const translatedTags = translated.match(/<[^>]+>/g) || [];
      return originalTags.length === translatedTags.length;
    },
  };

  return Object.entries(checks).every(([name, check]) => {
    const result = check();
    if (!result) {
      console.warn(`Çeviri doğrulama başarısız: ${name}`);
    }
    return result;
  });
}

Yaygın Sorunları Giderme

Derleme Zamanı Sorunları

Derleme sorunlarıyla karşılaştığınızda:

1. Önbelleği Temizle: .lingo-cache dizinini kaldırın ve yeniden derleyin
2. Yapılandırmayı Doğrula: Tüm yerel ayarların ISO standartlarına uyduğundan emin olun
3. Bağımlılıkları Kontrol Et: Lingo.dev'in en son sürümüne güncelleyin
4. Günlükleri İncele: DEBUG=lingo:* ile ayrıntılı günlük kaydını etkinleştirin

Çalışma Zamanı Zorlukları

SDK ile ilgili sorunlar için:

1. API Anahtarı Doğrulaması: Anahtar izinlerini ve kotalarını doğrulayın
2. Ağ Zaman Aşımları: Üstel geri çekilmeyle yeniden deneme mantığı uygulayın
3. Hız Sınırlama: İstek kuyruklama ve kısıtlamayı kullanın
4. Geri Dönüş Stratejileri: Her zaman zarif düşüş sağlayın

Sonuç

Lingo.dev, uygulama yerelleştirmesine yaklaşımımızda temel bir değişimi temsil ediyor. Yapay zeka destekli çeviriyi geliştirici dostu araçlarla birleştirerek, bir zamanlar karmaşık ve zaman alan bir süreci otomatik, verimli bir iş akışına dönüştürüyor. İster küçük bir web sitesi ister büyük ölçekli bir uygulama oluşturuyor olun, Lingo.dev'in modüler mimarisi, küresel kitlelere etkili bir şekilde ulaşmak için gereken esnekliği ve gücü sağlar.

Lingo.dev ile başarının anahtarı, bileşenlerini anlamak ve her yerelleştirme zorluğu için doğru aracı seçmektir. Statik React içeriği için Derleyiciyi kullanın, yapılandırma ve dokümantasyon için CLI'dan yararlanın, CI/CD entegrasyonu ile otomatikleştirin ve SDK ile dinamik içeriği yönetin. Bu eğitimde belirtilen uygulamaları takip ederek, dünya çapındaki kullanıcılarla yankılanan gerçekten çok dilli uygulamalar oluşturmak için iyi donanımlı olacaksınız.

Lingo.dev ile yolculuğunuza devam ederken, yerelleştirmenin sadece çeviriyle ilgili olmadığını, kullanıcılarla kendi ana dillerinde anlamlı bağlantılar kurmakla ilgili olduğunu unutmayın. Lingo.dev'in akıllı otomasyonu ve düşünceli uygulamanızla bu hedefe her zamankinden daha etkili bir şekilde ulaşabilirsiniz.