Μετάφραση δομημένου περιεχομένου από PHP με το PolyLingo SDK

Το PolyLingo PHP SDK είναι πλέον διαθέσιμο στο Packagist. Εγκαταστήστε το με το Composer, δώστε του μια συμβολοσειρά απλού κειμένου, Markdown, JSON ή HTML και λάβετε μεταφράσεις σε κάθε γλώσσα που χρειάζεστε — χωρίς να γράψετε ωμό HTTP ή να ανησυχείτε ότι η δομή σας θα καταστραφεί κατά τη μεταφορά.

Αυτή η ανάρτηση καλύπτει την εγκατάσταση, την αυθεντικοποίηση και όλη την επιφάνεια του SDK: συγχρονισμένη μετάφραση, παρτίδες αιτημάτων, ασύγχρονα έργα και διαχείριση σφαλμάτων.

---

Εγκατάσταση

Απαιτεί PHP 7.4 ή νεότερη έκδοση. Εγκαταστήστε μέσω Composer:

composer require usepolylingo/polylingo

Το SDK εξαρτάται από τα guzzlehttp/guzzle ^7.8 και psr/http-client ^1.0. Και τα δύο εγκαθίστανται αυτόματα.

---

Ρύθμιση του πελάτη

Δημιουργήστε μια μοναδική παρουσία PolyLingo και επαναχρησιμοποιήστε την σε όλη την εφαρμογή σας. Η μόνη απαιτούμενη επιλογή είναι το κλειδί API σας:

<?php
use PolyLingo\PolyLingo;

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

Αποθηκεύστε το κλειδί API σε μια μεταβλητή περιβάλλοντος. Μην το κωδικοποιείτε σκληρά ή δεσμεύετε στον έλεγχο έκδοσης.

Δύο προαιρετικές ρυθμίσεις που αξίζει να γνωρίζετε:

$client = new PolyLingo([
    'apiKey'  => getenv('POLYLINGO_API_KEY'),
    'baseURL' => 'https://api.usepolylingo.com/v1', // προεπιλογή, παρακαμφθείτε για αυτο-φιλοξενούμενες περιπτώσεις
    'timeout' => 120_000,                           // χιλιοστά του δευτερολέπτου, προεπιλογή 120000 (2 λεπτά)
]);

---

Μετάφραση περιεχομένου

Απλό κείμενο, Markdown, JSON ή HTML

Περάστε το περιεχόμενό σας και έναν πίνακα με κωδικούς γλωσσών στόχου στο translate(). Το πεδίο format λέει στο SDK τι είδους περιεχόμενο χειρίζεται:

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

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

Η επιλογή format δέχεται plain, markdown, json ή html. Αν το παραλείψετε, το API ανιχνεύει αυτόματα το format από το περιεχόμενο. Μπορείτε επίσης να περάσετε μια υπόδειξη γλώσσας source και μια τιμή model standard (προεπιλογή) ή advanced.

Η διατήρηση της μορφής είναι η βασική συμπεριφορά εδώ. Για περιεχόμενο json, μεταφράζονται μόνο οι τιμές συμβολοσειρών. Τα κλειδιά, οι εμφωλεύσεις, οι πίνακες και οι μη-συμβολοσειρές επιστρέφουν ακριβώς όπως τα στείλατε. Για markdown, οι επικεφαλίδες παραμένουν επικεφαλίδες, τα μπλοκ κώδικα παραμένουν αυτούσια και οι διευθύνσεις URL των συνδέσμων δεν αγγίζονται. Για html, οι ετικέτες και τα χαρακτηριστικά διατηρούνται και μεταφράζονται μόνο οι κόμβοι κειμένου.

Μετάφραση αρχείου τοπικής ρύθμισης JSON

Ένα κοινό σενάριο χρήσης είναι η μετάφραση ενός αρχείου τοπικής ρύθμισης. Στείλτε ολόκληρο το αντικείμενο ως συμβολοσειρά JSON:

$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"
    );
}

Ένα αίτημα χειρίζεται και τις τρεις τοπικές ρυθμίσεις. Τα κλειδιά παραμένουν ανέπαφα σε κάθε αρχείο εξόδου.

---

Αιτήματα παρτίδας

Χρησιμοποιήστε το batch() όταν έχετε πολλά ξεχωριστά στοιχεία περιεχομένου για μετάφραση. Μπορείτε να στείλετε έως 100 στοιχεία σε ένα αίτημα, το καθένα με το δικό του id και προαιρετικό format:

$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";
}

Όλα τα στοιχεία μοιράζονται τον ίδιο πίνακα targets. Η απάντηση διατηρεί το id που περάσατε για κάθε στοιχείο, ώστε να μπορείτε να αντιστοιχίσετε τα αποτελέσματα πίσω στα αρχικά σας δεδομένα χωρίς να βασίζεστε στη σειρά.

---

Ασύγχρονα έργα

Για μεταφράσεις μεγάλης διάρκειας (μεγάλα έγγραφα, πολλοί στόχοι ή και τα δύο) το API εργασιών δέχεται ένα αίτημα, επιστρέφει αμέσως με ένα job_id και σας επιτρέπει να κάνετε polling για το αποτέλεσμα. Το SDK το χειρίζεται με δύο τρόπους.

Ενσωμάτωση και polling χειροκίνητα

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

$jobId = $accepted['job_id'];

// Κάντε polling μέχρι η εργασία να φτάσει σε τελικό στάτους
 do {
    sleep(5);
    $state = $client->jobs->get($jobId);
} while ($state['status'] === 'pending' || $state['status'] === 'processing');

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

Μια κλήση που κάνει polling μέχρι να ολοκληρωθεί

Αν δεν χρειάζεστε χειροκίνητο έλεγχο, το jobs->translate() χειρίζεται το polling για εσάς:

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

    // Προαιρετικές παρακάμψεις (εμφανίζονται οι προεπιλογές):
    // 'pollInterval' => 5000,       // ms μεταξύ polling, προεπιλογή 5000
    // 'timeout'      => 1_200_000,  // συνολικός χρόνος αναμονής, προεπιλογή 20 λεπτά
    // 'onProgress'   => function (?int $queuePosition) {
    //     echo "Queue position: {$queuePosition}\n";
    // },
]);

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

Η συνάρτηση onProgress καλείται σε κάθε polling με τη θέση στην ουρά αν η API την επιστρέφει, ή null αν δεν είναι διαθέσιμη. Χρησιμοποιήστε την για να καταγράψετε την πρόοδο ή να ενημερώσετε το UI.

---

Βοηθητικά endpoints

Τρία ελαφριά endpoints δεν χρειάζονται παραμέτρους πέρα από την αυθεντικοποίηση:

$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 και GET /languages δεν απαιτούν κλειδί API. GET /usage επιστρέφει την κατανάλωση tokens για τον τρέχοντα ημερολογιακό μήνα για τον αυθεντικοποιημένο λογαριασμό.

---

Διαχείριση σφαλμάτων

Όλα τα σφάλματα του SDK επεκτείνουν το PolyLingo\Errors\PolyLingoException. Πιάστε τους συγκεκριμένους υποτύπους που θέλετε να χειριστείτε διαφορετικά:

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 — άκυρο, λείπει ή ανακληθέν κλειδί API
} catch (RateLimitException $e) {
    // HTTP 429 — όριο ανά λεπτό επιτεύχθηκε
    $retryAfter = $e->getRetryAfter(); // int|null δευτερόλεπτα
} catch (JobFailedException $e) {
    // Ασύγχρονη εργασία έφτασε σε αποτυχημένη τελική κατάσταση
    $jobId = $e->getJobId();
} catch (PolyLingoException $e) {
    // Όλα τα άλλα σφάλματα API
    $httpStatus = $e->getHttpStatus();
    $errorCode  = $e->getErrorCode(); // π.χ. "invalid_request", "translation_error"
}

Το RateLimitException::getRetryAfter() επιστρέφει τον αριθμό δευτερολέπτων που πρέπει να περιμένετε πριν ξαναδοκιμάσετε αν η API περιλαμβάνει αυτή την κεφαλίδα, ή null αν δεν υπάρχει. Το JobFailedException::getJobId() σας δίνει το ID της αποτυχημένης εργασίας ώστε να το καταγράψετε ή να το εμφανίσετε στον χρήστη.

---

Γρήγορη αναφορά

Μέθοδος	Endpoint	Απαιτεί αυθεντικοποίηση
$client->health()	GET /health	Όχι
$client->languages()	GET /languages	Όχι
$client->translate()	POST /translate	Ναι
$client->batch()	POST /translate/batch	Ναι
$client->usage()	GET /usage	Ναι
$client->jobs->create()	POST /jobs	Ναι
$client->jobs->get($id)	GET /jobs/:id	Ναι
$client->jobs->translate()	POST /jobs + polling	Ναι

---

Ξεκινήστε

Το SDK είναι στο Packagist στο usepolylingo/polylingo. Η πλήρης τεκμηρίωση API είναι στο usepolylingo.com/docs.

Το δωρεάν επίπεδο περιλαμβάνει 50.000 tokens ανά μήνα. Δεν απαιτείται πιστωτική κάρτα.

composer require usepolylingo/polylingo

Αποκτήστε το κλειδί API σας