BeLocal Docs
SdkPhp

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/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(['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): BeLocalEngine

t() -- translate single text

$engine->t(string $text, string $lang, ?string $sourceLang = null, string $userContext = '', bool $managed = false): string
ParameterTypeDescriptionDefault
$textstringText to translateRequired
$langstringTarget language code (e.g., 'fr', 'es')Required
$sourceLangstring|nullSource language (null = auto-detect)null
$userContextstringContext to improve translation accuracy (optional)''
$managedboolUse managed translations cachefalse

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 = [])
ParameterTypeDescription
$textsarray<string>Texts to translate
$langstringTarget language code
$sourceLangstring|nullSource language (null = auto-detect). Optional, defaults to null.
$contextarray<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 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

On this page