PHP SDK (polylingo)

Official PHP client for the PolyLingo REST API. Uses Guzzle and supports PHP 7.4+.

• Packagist: usepolylingo/polylingo
• Source: UsePolyLingo/polylingo-php

For raw HTTP details, see API reference.

Installation

composer require usepolylingo/polylingo

PHP: >= 7.4

Constructor

<?php

use PolyLingo\PolyLingo;

$client = new PolyLingo([
    'apiKey'   => getenv('POLYLINGO_API_KEY'), // required
    'baseURL'  => 'https://api.usepolylingo.com/v1', // optional; this is the default
    'timeout'  => 120000, // optional; request timeout in milliseconds (default 120_000)
]);

Methods

$client->health()

GET /health. Returns an associative array ['status' => …, 'timestamp' => …].

$h = $client->health();

$client->languages()

GET /languages. Returns the supported language list.

$data = $client->languages();
$langs = $data['languages'];

$client->translate($params)

POST /translate

$r = $client->translate([
    'content' => '# Hello',
    'targets' => ['es', 'fr'],
    'format'  => 'markdown', // optional; omit to auto-detect
    'source'  => 'en',       // optional hint
    'model'   => 'standard', // optional: 'standard' | 'advanced'
]);

$r['translations']['es']; // string
$r['usage']['total_tokens'];
$r['usage']['input_tokens'];
$r['usage']['output_tokens'];

$client->batch($params)

POST /translate/batch

$b = $client->batch([
    'items' => [
        ['id' => 'a', 'content' => 'Hello'],
        ['id' => 'b', 'content' => '## Title', 'format' => 'markdown'],
    ],
    'targets' => ['de'],
    'source'  => 'en',       // optional
    'model'   => 'standard', // optional
]);

$b['results'][0]['translations']['de'];
$b['usage']['total_tokens'];

$client->usage()

GET /usage. Returns plan usage for the authenticated key.

$u = $client->usage();

Jobs ($client->jobs)

$client->jobs->create($params)

POST /jobs. Enqueues async work and returns the 202 body (job_id, status, created_at, …).

$job = $client->jobs->create([
    'content' => $longMarkdown,
    'targets' => ['de', 'fr'],
    'format'  => 'markdown',
]);
echo $job['job_id'];

$client->jobs->get($jobId)

GET /jobs/:id. When status === 'completed', the response includes translations and usage at the top level.

$status = $client->jobs->get($job['job_id']);

$client->jobs->translate($params) (convenience)

Submits a job, then polls until completed or failed, or until the timeout is reached.

All time values are in milliseconds:

$done = $client->jobs->translate([
    'content'      => $longMarkdown,
    'targets'      => ['de', 'fr', 'es'],
    'format'       => 'markdown',
    'pollInterval' => 5000,     // ms between polls; default 5_000
    'timeout'      => 1200000,  // **total** ms budget; default 1_200_000 (20 min)
    'onProgress'   => function (int $queuePosition): void {
        echo "Queue position: $queuePosition\n";
    },
]);

$done['translations']['de'];
$done['usage']['total_tokens'];

Job lifecycle statuses: pending, processing, completed, failed.

Error handling

All failures throw subclasses of PolyLingo\Errors\PolyLingoException:

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

try {
    $client->translate(['content' => 'Hi', 'targets' => ['es']]);
} catch (AuthException $e) {
    echo "Auth failed: {$e->getHttpStatus()} {$e->getErrorCode()}";
} catch (RateLimitException $e) {
    echo "Rate limited. Retry after {$e->getRetryAfter()}s";
} catch (JobFailedException $e) {
    echo "Job {$e->getJobId()} failed: {$e->getMessage()}";
} catch (PolyLingoException $e) {
    echo "API error {$e->getHttpStatus()}: {$e->getErrorCode()} — {$e->getMessage()}";
}

Async jobs pattern (summary)

1. Fire-and-forget polling: $jobs->create → your worker calls $jobs->get on an interval until completed or failed.
2. Built-in polling: $jobs->translate. Same semantics, with pollInterval, timeout, and onProgress.

Large payloads and long-running translations should prefer jobs over synchronous translate to avoid HTTP timeouts.

Changelog

0.1.0

• Initial release: health, languages, translate, batch, usage, jobs->create, jobs->get, jobs->translate.