belocal/sdk

PHP library for text translation via API

1.0.6 2026-04-16 09:52 UTC

Requires

• php: >=7.4
• ext-curl: *
• ext-json: *

Requires (Dev)

• phpunit/phpunit: ^11.0

MIT

• bobredobre

README

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/sdk

Usage

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 section

tMany() with managed cache

$translated = $translator->tMany(['Hello', 'Goodbye'], 'fr', null, '', true);
// Editing the result becomes available in the Managed Translations section

translateRequest() — single request with full control

use BeLocal\TranslateRequest;

$request = $translator->translateRequest(
    new TranslateRequest(['<p>Hello</p>'], 'fr', null, [
        TranslateRequest::CTX_KEY_MARKUP => TranslateRequest::MARKUP_HTML,
    ])
);

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): BeLocalEngine

t() -- 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): array

Same parameters as t(), but $texts is array<string>. Returns array<string>.

translateRequest() -- single request with full result

$engine->translateRequest(TranslateRequest $request): TranslateRequest

Returns the same TranslateRequest object with its result property filled.

translateMultiRequest() -- batch requests in one API call

$engine->translateMultiRequest(array $requests): array

Takes 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, translation_style, markup.

Methods: getTexts(), getLang(), getSourceLang(), getContext(), getRequestId(), isCompleted(), isSuccessful(), getResult().

Context keys: CTX_KEY_USER_TYPE, CTX_KEY_USER_CONTEXT, CTX_KEY_CACHE_TYPE, CTX_KEY_ENTITY_KEY, CTX_KEY_ENTITY_ID, CTX_KEY_TRANSLATION_STYLE, CTX_KEY_MARKUP. cache_type values: CACHE_TYPE_TEMPORARY, CACHE_TYPE_MANAGED, CACHE_TYPE_NO_CACHE. translation_style values: TRANSLATION_STYLE_AUTO, TRANSLATION_STYLE_FORMAL, TRANSLATION_STYLE_INFORMAL, TRANSLATION_STYLE_TECHNICAL, TRANSLATION_STYLE_MARKETING, TRANSLATION_STYLE_LITERARY. markup values: MARKUP_HTML, MARKUP_XML, MARKUP_CUSTOM.

TranslateManyResult

Result of a translation request.

Methods:

• getTexts(): ?array -- translated texts or null on failure
• isOk(): bool -- whether translation succeeded
• getError(): ?BeLocalError -- error object or null
• getHttpCode(): ?int -- HTTP response code
• getCurlErrno(): ?int -- cURL error number
• getRaw(): ?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