better-i18n REST API & SDK: Programatik Çeviri Yönetimi

better-i18n platformu, geliştiricilere çeviri yönetimi üzerinde tam programatik erişim sağlar — TypeScript SDK, REST API, CLI araçları ve yapay zeka asistanları için MCP server aracılığıyla. Key'leri, çevirileri, dilleri ve içerikleri kendi kodunuzdan ve CI pipeline'larınızdan yönetin.

İki API, Farklı Amaçlar

better-i18n, neyi geliştirdiğinize bağlı olarak iki farklı API sunar:

API	Base URL	Auth	Kullanım Alanı
Translation API	`dash.better-i18n.com/api`	Bearer token	Key yönetimi, çeviriler, diller, sync'ler
Content API	`content.better-i18n.com`	`x-api-key` header	Headless CMS — blog yazıları, pazarlama sayfaları, yapılandırılmış içerik

Her iki API de JSON istek/yanıt gövdeleri kullanır ve REST kurallarına uyar.

Kimlik Doğrulama

Dashboard üzerindeki Settings → API Keys bölümünden API key'leri oluşturun.

# Translation API (key yönetimi, çeviriler)
curl -H "Authorization: Bearer bi18_live_abc123..." \
  https://dash.better-i18n.com/api/...

# Content API (headless CMS)
curl -H "x-api-key: bi-your-api-key" \
  https://content.better-i18n.com/v1/content/acme/web-app/models

API key'leri asla istemci tarafı kodda açığa çıkarmayın. Environment variable'lar ve sunucu tarafı proxy'ler kullanın.

Translation API

Translation API, temel i18n iş akışını yönetir: projeler, key'ler, çeviriler ve diller.

Projeler

listProjects()          → Erişiminiz olan tüm projeleri listeleyin
getProject(project)     → Proje detaylarını, dilleri ve namespace'leri alın

Her proje org/project formatıyla tanımlanır (örneğin acme/web-app). Bunu i18n.config.ts dosyanızda bulabilirsiniz.

Translation Key'leri

listKeys(project, options)    → Translation key'lerini arayın ve listeleyin
createKeys(project, keys)     → Kaynak metin ve çevirilerle key oluşturun
updateKeys(project, updates)  → Mevcut key'lerin çevirilerini güncelleyin
deleteKeys(project, keys)     → Translation key'lerini soft-delete yapın

Tek çağrıda çevirilerle birlikte key oluşturun:

{
  "project": "acme/web-app",
  "keys": [
    {
      "name": "auth.login.title",
      "namespace": "auth",
      "sourceText": "Sign in to your account",
      "translations": {
        "tr": "Hesabınıza giriş yapın",
        "de": "Melden Sie sich bei Ihrem Konto an"
      }
    },
    {
      "name": "auth.login.button",
      "namespace": "auth",
      "sourceText": "Sign in"
    }
  ]
}

Key'leri arayın ve filtreleyin:

{
  "project": "acme/web-app",
  "search": "login",
  "namespaces": ["auth"],
  "missingLanguage": "tr"
}

Çevirileri status ile güncelleyin:

{
  "project": "acme/web-app",
  "translations": [
    {
      "key": "auth.login.title",
      "language": "tr",
      "text": "Hesabınıza giriş yapın",
      "status": "approved"
    }
  ]
}

Diller

addLanguage(project, language)   → Yeni bir hedef dil ekleyin
getProject(project)              → Tüm aktif dilleri ve ilerlemeyi görün

Sync İşlemleri

getSyncs(project)    → Son sync işlemlerini listeleyin (GitHub, CDN, vb.)
getSync(project, id) → Belirli bir sync job'ının detaylarını alın

Content SDK

@better-i18n/sdk, Content API için bir TypeScript istemcisidir — blog yazıları, changelog girişleri ve pazarlama sayfaları gibi yapılandırılmış içerikler için headless CMS'imiz.

Kurulum

npm install @better-i18n/sdk

Başlatma

import { createClient } from "@better-i18n/sdk";

const client = createClient({
  project: "acme/web-app",
  apiKey: process.env.BETTER_I18N_API_KEY!,
});

Query Builder (Supabase tarzı)

SDK, zincirlenebilir ve immutable bir query builder sunar:

// Yayınlanmış blog yazılarını listeleyin
const { data: posts, total, hasMore } = await client
  .from("blog-posts")
  .eq("status", "published")
  .order("publishedAt", { ascending: false })
  .expand("author", "category")
  .limit(10);

// Fransızca tek bir entry alın
const { data: post } = await client
  .from("blog-posts")
  .language("fr")
  .single("getting-started");

console.log(post.title, post.body);

Kullanılabilir Metodlar

Metod	Açıklama
`.eq(field, value)`	Tam değere göre filtreleyin
`.search(term)`	Başlıklarda tam metin arama
`.language(code)`	Yerelleştirilmiş içerik için dil belirleyin
`.order(field, opts)`	`publishedAt`, `createdAt`, `updatedAt` veya `title`'a göre sıralayın
`.limit(n)`	Sayfa başına entry sayısı (1–100)
`.page(n)`	Sayfa numarası
`.expand(...fields)`	İlişki alanlarını satır içi genişletin
`.select(...fields)`	Döndürülecek alanları seçin
`.single(slug)`	Slug'a göre tek bir entry alın

REST Endpoint'leri (Arka Planda)

SDK bu endpoint'leri çağırır:

Metod	Endpoint
`GET`	`/v1/content/{org}/{project}/models`
`GET`	`/v1/content/{org}/{project}/models/{model}/entries`
`GET`	`/v1/content/{org}/{project}/models/{model}/entries/{slug}`

CLI Araçları

@better-i18n/cli, geliştirme iş akışınıza entegre olur:

# Kod tabanınızdaki hardcoded string'leri tespit edin
better-i18n scan

# Yerel key'leri bulut projesiyle karşılaştırın
better-i18n sync

# JSON çıktısıyla CI/CD entegrasyonu
better-i18n scan --ci --format json
better-i18n sync --format json

CLI, useTranslations() ve getTranslations() hook'larını otomatik olarak algılar, namespace'leri çıkarır ve eksik çevirileri raporlar — tipik kod tabanları için 100ms'nin altında.

Pre-commit & CI Entegrasyonu

# Pre-commit hook
npx @better-i18n/cli scan --staged --ci

# GitHub Actions
- run: npx @better-i18n/cli scan --ci --format json

Yapay Zeka Asistanları için MCP Server

better-i18n MCP (Model Context Protocol) server, Claude, Cursor ve Windsurf gibi yapay zeka asistanlarının doğrudan IDE'nizden çevirileri yönetmesine olanak tanır:

# MCP server'ı kurun
npm install @better-i18n/mcp

Yapay zeka asistanları şunları yapabilir:

Translation key'lerini listeleyin ve arayın
Çevirilerle birlikte yeni key'ler oluşturun
Mevcut çevirileri güncelleyin
Sync durumunu kontrol edin
Yeni diller ekleyin

Bu sayede "Auth namespace için Almanca çeviriler ekle" diyebilir ve yapay zeka asistanınız bunu API aracılığıyla halleder.

CDN Dağıtımı

Çeviriler, öngörülebilir bir URL deseniyle CDN aracılığıyla global olarak sunulur:

https://cdn.better-i18n.com/{org}/{project}/{locale}/{namespace}.json

Örneğin:

https://cdn.better-i18n.com/acme/web-app/de/common.json

Deploy gerekmez — çeviriler yayınlandığında CDN üzerinde otomatik olarak güncellenir.

Platform SDK'ları

Paket	Amaç
`@better-i18n/sdk`	Content API istemcisi (TypeScript)
`@better-i18n/cli`	Kod tarama & sync (CLI)
`@better-i18n/next`	Next.js runtime entegrasyonu
`@better-i18n/use-intl`	React çeviri hook'ları
`@better-i18n/mcp`	Yapay zeka asistanları için MCP server

Tüm paketler npm'de mevcuttur ve yerel fetch() ile herhangi bir JavaScript runtime'ında çalışır.

İlgili Kaynaklar

Git Entegrasyonu — Pull request'ler aracılığıyla çevirileri repository'nizle sync edin
Webhook'lar & Olaylar — Çeviri olayları için gerçek zamanlı bildirimler
Tam API Dokümantasyonu — Kapsamlı endpoint referansı

better-i18n REST API & SDK: Programatik Çeviri Yönetimi