belocal/sdk
belocal/sdk
A PHP library for text translation via API with HTTP/1.1 keep-alive support.
Requirements
- PHP 7.4 or higher
- cURL extension
- JSON extension
Installation
Install via Composer:
composer require belocal/sdkUsage
Initialization
<?php
require_once 'vendor/autoload.php';
use BeLocal\BeLocalEngine;
$translator = BeLocalEngine::withApiKey('your-api-key-here');
$translated = $translator->t('Hello, world!', 'fr');
// "Bonjour, monde !"t() — translate single text
$translated = $translator->t('crane', 'ru', 'en', 'Website for construction services');
// Optional context clarifies which translation to use
// "кран"tMany() — translate multiple texts
$translated = $translator->tMany(['Hello, world!', 'Goodbye'], 'fr');
// ['Bonjour, monde !', 'Au revoir']t() with managed cache
$translated = $translator->t('Hello', 'fr', null, '', true);
// Editing the result becomes available in the Managed Translations sectiontMany() with managed cache
$translated = $translator->tMany(['Hello', 'Goodbye'], 'fr', null, '', true);
// Editing the result becomes available in the Managed Translations sectiontranslateRequest() — single request with full control
use BeLocal\TranslateRequest;
$request = $translator->translateRequest(
new TranslateRequest(['Hello'], 'fr')
);
if ($request->isSuccessful()) {
$texts = $request->getResult()->getTexts();
}translateMultiRequest() — batch requests
$requests = [
new TranslateRequest(['Hello world', 'How are you?'], 'es', 'en'),
new TranslateRequest(['Good morning'], 'fr'),
];
$requests = $translator->translateMultiRequest($requests);
foreach ($requests as $request) {
if ($request->isSuccessful()) {
$texts = $request->getResult()->getTexts();
}
}Error handling
t() and tMany() return the original text on error. For explicit error handling, use translateRequest():
$request = $translator->translateRequest(
new TranslateRequest(['Hello'], 'fr')
);
$result = $request->getResult();
if ($result->isOk()) {
echo $result->getTexts()[0];
} else {
echo "Error: " . $result->getError()->getMessage();
}API Reference
BeLocalEngine
Factory
BeLocalEngine::withApiKey(string $apiKey, int $timeout = 30): BeLocalEnginet() -- translate single text
$engine->t(string $text, string $lang, ?string $sourceLang = null, string $userContext = '', bool $managed = false): string| Parameter | Type | Description | Default |
|---|---|---|---|
| $text | string | Text to translate | Required |
| $lang | string | Target language code (e.g., 'fr', 'es') | Required |
| $sourceLang | string|null | Source language (null = auto-detect) | null |
| $userContext | string | Context to improve translation accuracy (optional) | '' |
| $managed | bool | Use managed translations cache | false |
Returns translated text, or original text on error.
tMany() -- translate multiple texts
$engine->tMany(array $texts, string $lang, ?string $sourceLang = null, string $userContext = '', bool $managed = false): arraySame parameters as t(), but $texts is array<string>. Returns array<string>.
translateRequest() -- single request with full result
$engine->translateRequest(TranslateRequest $request): TranslateRequestReturns the same TranslateRequest object with its result property filled.
translateMultiRequest() -- batch requests in one API call
$engine->translateMultiRequest(array $requests): arrayTakes array<TranslateRequest>, returns the same array with results filled. Throws \InvalidArgumentException if array is empty.
TranslateRequest
new TranslateRequest(array $texts, string $lang, ?string $sourceLang = null, array $context = [])| Parameter | Type | Description |
|---|---|---|
| $texts | array<string> | Texts to translate |
| $lang | string | Target language code |
| $sourceLang | string|null | Source language (null = auto-detect). Optional, defaults to null. |
| $context | array<string, string> | Context key-value pairs. Optional, defaults to []. May include user_ctx, entity_key, entity_id, cache_type, user_type. |
Methods: getTexts(), getLang(), getSourceLang(), getContext(), getRequestId(), isCompleted(), isSuccessful(), getResult().
TranslateManyResult
Result of a translation request.
Methods:
getTexts(): ?array-- translated texts or null on failureisOk(): bool-- whether translation succeededgetError(): ?BeLocalError-- error object or nullgetHttpCode(): ?int-- HTTP response codegetCurlErrno(): ?int-- cURL error numbergetRaw(): ?string-- raw response body
BeLocalError
Error value object with code constants and message.
Constants: INVALID_API_KEY, PAYMENT_REQUIRED, NETWORK, HTTP_NON_200, DECODE, API_SCHEMA, JSON_UTF8, JSON_ENCODE, UNCAUGHT, UNKNOWN.
Methods: getCode(): string, getMessage(): string.
Features
- PHP 7.4+ compatible
- HTTP/1.1 keep-alive connections via cURL
- Graceful error handling (original text returned on error)
- Deterministic request IDs for deduplication
- PSR-4 autoloading
- Zero external dependencies
License
MIT