← Bloga geri dön
Terminal window showing a Composer install command for the PolyLingo PHP SDK alongside a short PHP translate call and its JSON output.

PolyLingo SDK ile PHP'den yapılandırılmış içeriği çevirin

By Robert M

PolyLingo SDK ile PHP'den yapılandırılmış içeriği çevirme

PolyLingo PHP SDK artık Packagist'te mevcut. Composer ile kurun, düz metin, Markdown, JSON veya HTML içeren bir dize verin ve ihtiyacınız olan her dilde çeviriler alın — ham HTTP yazmadan veya yapınızın iletim sırasında bozulmasından endişe etmeden.

Bu yazı kurulum, kimlik doğrulama ve SDK'nın tüm yüzeyini kapsar: senkron çeviri, toplu istekler, asenkron işler ve hata yönetimi.

Kurulum

PHP 7.4 veya daha yeni sürüm gerektirir. Composer ile kurun:

composer require usepolylingo/polylingo

SDK, guzzlehttp/guzzle ^7.8 ve psr/http-client ^1.0 bağımlılıklarına sahiptir. İkisi de otomatik olarak çekilir.

İstemciyi ayarlama

Tek bir PolyLingo örneği oluşturun ve uygulamanızda tekrar kullanın. Tek gerekli seçenek API anahtarınızdır:

<?php
use PolyLingo\PolyLingo;

$client = new PolyLingo([
    'apiKey' => getenv('POLYLINGO_API_KEY'),
]);

API anahtarınızı bir ortam değişkeninde saklayın. Asla kod içine sert kodlamayın veya sürüm kontrolüne eklemeyin.

Bilmeniz gereken iki isteğe bağlı ayar:

$client = new PolyLingo([
    'apiKey'  => getenv('POLYLINGO_API_KEY'),
    'baseURL' => 'https://api.usepolylingo.com/v1', // varsayılan, kendi barındırdığınız örnekler için geçersiz kılın
    'timeout' => 120_000,                           // milisaniye, varsayılan 120000 (2 dakika)
]);

İçerik çevirme

Düz metin, Markdown, JSON veya HTML

İçeriğinizi ve hedef dil kodlarından oluşan bir diziyi translate() fonksiyonuna geçirin. format alanı SDK'ya hangi tür içerikle uğraştığını söyler:

$result = $client->translate([
    'content' => '# Hello',
    'targets' => ['es', 'fr', 'de'],
    'format'  => 'markdown',
]);

$es     = $result['translations']['es'];
$tokens = $result['usage']['total_tokens'];

format seçeneği plain, markdown, json veya html değerlerini kabul eder. Eğer belirtmezseniz, API içeriğe göre formatı otomatik algılar. Ayrıca bir source dil ipucu ve standard (varsayılan) veya advanced değerinde bir model geçebilirsiniz.

Format koruma burada ana davranıştır. json içeriği için sadece string değerler çevrilir. Anahtarlar, iç içe yapılar, diziler ve string olmayan türler tam olarak gönderdiğiniz gibi geri gelir. markdown için başlıklar başlık olarak kalır, kod blokları olduğu gibi bırakılır ve bağlantı URL'lerine dokunulmaz. html için etiketler ve öznitelikler korunur ve sadece metin düğümleri çevrilir.

JSON locale dosyası çevirme

Yaygın bir kullanım durumu locale dosyasını çevirmektir. Tüm nesneyi JSON dizesi olarak gönderin:

$source = json_decode(file_get_contents('messages/en.json'), true);

$result = $client->translate([
    'content' => json_encode($source),
    'format'  => 'json',
    'targets' => ['de', 'fr', 'ja'],
]);

foreach (['de', 'fr', 'ja'] as $locale) {
    $translated = json_decode($result['translations'][$locale], true);
    file_put_contents(
        "messages/{$locale}.json",
        json_encode($translated, JSON_PRETTY_PRINT | JSON_UNESCAPED_UNICODE) . "\n"
    );
}

Tek bir istek üç locale'yi de işler. Anahtarlar her çıktı dosyasında dokunulmaz.

Toplu istekler

Çevrilecek birden fazla ayrı içerik öğeniz varsa batch() kullanın. Tek bir istekte 100 öğeye kadar gönderebilirsiniz, her biri kendi id ve isteğe bağlı format ile:

$batch = $client->batch([
    'items' => [
        ['id' => 'hero_title',    'content' => 'Welcome back',              'format' => 'plain'],
        ['id' => 'hero_subtitle', 'content' => 'Here is what is new today', 'format' => 'plain'],
        ['id' => 'cta',           'content' => 'Get started',               'format' => 'plain'],
    ],
    'targets' => ['es', 'fr'],
]);

foreach ($batch['results'] as $row) {
    echo $row['id'] . ': ' . $row['translations']['es'] . "\n";
}

Tüm öğeler aynı targets dizisini paylaşır. Yanıt, her öğe için gönderdiğiniz idyi korur, böylece sonuçları orijinal verilerinize sıraya bağlı kalmadan eşleyebilirsiniz.

Asenkron işler

Uzun süren çeviriler (büyük belgeler, çok sayıda hedef veya her ikisi) için işler API'si bir istek kabul eder, hemen job_id ile yanıt verir ve sonucu sorgulamanıza izin verir. SDK bunu iki şekilde yönetir.

Elle kuyruğa alma ve sorgulama

$accepted = $client->jobs->create([
    'content' => file_get_contents('long-article.md'),
    'targets' => ['es', 'fr', 'de', 'ja', 'zh'],
    'format'  => 'markdown',
]);

$jobId = $accepted['job_id'];

// İş terminal durumuna ulaşana kadar sorgula
do {
    sleep(5);
    $state = $client->jobs->get($jobId);
} while ($state['status'] === 'pending' || $state['status'] === 'processing');

if ($state['status'] === 'complete') {
    $translations = $state['translations'];
}

Tamamlanana kadar sorgulayan tek çağrı

Manuel kontrol gerekmezse, jobs->translate() sorgulama döngüsünü sizin için yönetir:

$done = $client->jobs->translate([
    'content' => file_get_contents('long-article.md'),
    'targets' => ['es', 'fr', 'de'],
    'format'  => 'markdown',

    // İsteğe bağlı geçersiz kılmalar (varsayılanlar gösterilmiştir):
    // 'pollInterval' => 5000,       // sorgular arası ms, varsayılan 5000
    // 'timeout'      => 1_200_000,  // toplam bekleme süresi, varsayılan 20 dakika
    // 'onProgress'   => function (?int $queuePosition) {
    //     echo "Queue position: {$queuePosition}\n";
    // },
]);

$translations = $done['translations'];
$usage        = $done['usage'];

onProgress geri çağrısı, API bir sıra pozisyonu döndürürse her sorguda mevcut sıra pozisyonu ile tetiklenir, yoksa null olur. İlerlemeyi kaydetmek veya bir kullanıcı arayüzünü güncellemek için kullanın.

Yardımcı uç noktalar

Üç hafif uç nokta kimlik doğrulama dışında parametre gerektirmez:

$health = $client->health();
// ['status' => 'ok', 'timestamp' => '...']

$langs = $client->languages();
// ['languages' => [['code' => 'en', 'name' => 'English', 'rtl' => false], ...]]

$usage = $client->usage();
// ['usage' => ['tokens_used' => 12000, 'tokens_remaining' => 88000, ...]]

GET /health ve GET /languages API anahtarı gerektirmez. GET /usage kimlik doğrulanmış hesap için mevcut takvim ayının token tüketimini döner.

Hata yönetimi

Tüm SDK hataları PolyLingo\Errors\PolyLingoException sınıfını genişletir. Farklı şekilde ele almak istediğiniz alt türleri yakalayın:

use PolyLingo\Errors\AuthException;
use PolyLingo\Errors\JobFailedException;
use PolyLingo\Errors\PolyLingoException;
use PolyLingo\Errors\RateLimitException;

try {
    $result = $client->translate([
        'content' => '# Hello',
        'targets' => ['es'],
        'format'  => 'markdown',
    ]);
} catch (AuthException $e) {
    // HTTP 401 — geçersiz, eksik veya iptal edilmiş API anahtarı
} catch (RateLimitException $e) {
    // HTTP 429 — dakika başı limit aşıldı
    $retryAfter = $e->getRetryAfter(); // int|null saniye
} catch (JobFailedException $e) {
    // Asenkron iş başarısız terminal durumuna ulaştı
    $jobId = $e->getJobId();
} catch (PolyLingoException $e) {
    // Diğer tüm API hataları
    $httpStatus = $e->getHttpStatus();
    $errorCode  = $e->getErrorCode(); // örn. "invalid_request", "translation_error"
}

RateLimitException::getRetryAfter() API bu başlığı içeriyorsa yeniden denemeden önce beklenmesi gereken saniye sayısını döner, yoksa null. JobFailedException::getJobId() başarısız işin ID'sini verir, böylece kaydedebilir veya kullanıcıya gösterebilirsiniz.

Hızlı referans

YöntemUç NoktaKimlik doğrulama gerekli
$client->health()GET /healthHayır
$client->languages()GET /languagesHayır
$client->translate()POST /translateEvet
$client->batch()POST /translate/batchEvet
$client->usage()GET /usageEvet
$client->jobs->create()POST /jobsEvet
$client->jobs->get($id)GET /jobs/:idEvet
$client->jobs->translate()POST /jobs + sorgulamaEvet

Başlayın

SDK Packagist'te usepolylingo/polylingo adresinde. Tam API dokümantasyonu usepolylingo.com/docs adresinde.

Ücretsiz katman ayda 50.000 token içerir. Kredi kartı gerekmez.

composer require usepolylingo/polylingo

API anahtarınızı alın