README

Official PHP client for the Langbly translation API. Drop-in replacement for Google Translate v2.

Installation

composer require langbly/langbly-php

Requires PHP 7.4+ and Guzzle 7.

Quick Start

<?php
require_once 'vendor/autoload.php';

$client = new \Langbly\Client('your-api-key');

// Translate text
$result = $client->translate('Hello, world!', 'nl');
echo $result->text; // "Hallo, wereld!"

// Batch translate
$results = $client->translate(['Hello', 'Goodbye'], 'de');
foreach ($results as $t) {
    echo $t->text . "\n";
}

// Detect language
$detection = $client->detect('Bonjour');
echo $detection->language; // "fr"

// List languages
$languages = $client->languages('en');
foreach ($languages as $lang) {
    echo "{$lang->code}: {$lang->name}\n";
}

API Reference

Constructor

$client = new \Langbly\Client(
    apiKey: 'your-api-key',
    baseUrl: 'https://api.langbly.com',  // optional
    timeout: 30.0,                        // optional, seconds
    maxRetries: 2                         // optional
);

Parameter	Type	Default	Description
`apiKey`	string	required	Your Langbly API key
`baseUrl`	string	`https://api.langbly.com`	API base URL
`timeout`	float	`30`	Request timeout in seconds
`maxRetries`	int	`2`	Retries for transient errors (429, 5xx)

translate()

// Single string
$result = $client->translate('Hello', 'nl');
// Returns: Translation { text, source, model }

// Batch
$results = $client->translate(['Hello', 'Goodbye'], 'nl');
// Returns: Translation[]

// With options
$result = $client->translate('Hello', 'nl', 'en', 'html');

Parameter	Type	Required	Description
`text`	string/string[]	yes	Text or array of texts
`target`	string	yes	Target language code
`source`	string/null	no	Source language (auto-detected)
`format`	string/null	no	`"text"` or `"html"`

detect()

$detection = $client->detect('Bonjour le monde');
echo $detection->language;   // "fr"
echo $detection->confidence; // 0.98

languages()

// All languages
$languages = $client->languages();

// With localized names
$languages = $client->languages('en');
echo $languages[0]->code; // "af"
echo $languages[0]->name; // "Afrikaans"

Error Handling

use Langbly\Exceptions\LangblyException;
use Langbly\Exceptions\RateLimitException;
use Langbly\Exceptions\AuthenticationException;

try {
    $result = $client->translate('Hello', 'nl');
} catch (AuthenticationException $e) {
    // Invalid API key (401)
    echo "Auth error: " . $e->getMessage();
} catch (RateLimitException $e) {
    // Too many requests (429)
    $retryAfter = $e->getRetryAfter(); // seconds, or null
    echo "Rate limited. Retry after {$retryAfter}s";
} catch (LangblyException $e) {
    // Other API errors
    echo "Error ({$e->getStatusCode()}): " . $e->getMessage();
}

The client automatically retries transient errors (429, 500, 502, 503, 504) with exponential backoff. It respects the Retry-After header when present.

EU Data Residency

For EU-only data processing, use the EU endpoint:

$client = new \Langbly\Client('your-api-key', 'https://eu.langbly.com');

Laravel Integration

// config/services.php
'langbly' => [
    'api_key' => env('LANGBLY_API_KEY'),
],

// app/Providers/AppServiceProvider.php
use Langbly\Client as LangblyClient;

public function register()
{
    $this->app->singleton(LangblyClient::class, function () {
        return new LangblyClient(config('services.langbly.api_key'));
    });
}

// In a controller
public function translate(Request $request, LangblyClient $langbly)
{
    $result = $langbly->translate($request->input('text'), 'nl');
    return response()->json(['translated' => $result->text]);
}

Migrating from Google Translate

If you're currently using Google Cloud Translation, see the migration guide.

The API format is identical. Change the base URL and authentication:

// Before (Google)
$client->post('https://translation.googleapis.com/language/translate/v2', [
    'headers' => ['Authorization' => 'Bearer ' . $googleToken],
    'json' => ['q' => 'Hello', 'target' => 'nl'],
]);

// After (Langbly SDK)
$langbly = new \Langbly\Client($apiKey);
$result = $langbly->translate('Hello', 'nl');

License

MIT

langbly / langbly-php

Maintainers

Details