Skip to content

Commit 60ca47a

Browse files
davidturnbulldavidturnbull
committed
docs: revise docs for PHP SDK
1 parent cde45bd commit 60ca47a

File tree

2 files changed

+107
-50
lines changed

2 files changed

+107
-50
lines changed

‎src/LingoDotDevEngine.php‎

Lines changed: 96 additions & 50 deletions
Original file line numberDiff line numberDiff line change
@@ -16,9 +16,11 @@
1616
use Respect\Validation\Validator as v;
1717

1818
/**
19-
* LingoDotDevEngine class for interacting with the LingoDotDev API
20-
* A powerful localization engine that supports various content types including
21-
* plain text, objects, and chat sequences.
19+
* LingoDotDevEngine wraps the Lingo.dev localization API for PHP consumers.
20+
*
21+
* Use a single engine instance to translate strings, arrays, and chat logs, or
22+
* to detect the locale of free-form text. The engine handles request batching,
23+
* progress reporting, and surfacing validation or transport errors.
2224
*
2325
* @category Localization
2426
* @package Lingodotdev\Sdk
@@ -43,9 +45,17 @@ class LingoDotDevEngine
4345
private $_httpClient;
4446

4547
/**
46-
* Create a new LingoDotDevEngine instance
47-
*
48-
* @param array $config Configuration options for the Engine
48+
* Build an engine instance with your API key and optional batch settings.
49+
*
50+
* Provide at least ['apiKey' => '...']. You may override:
51+
* - 'apiUrl' with a valid base URL for the service (defaults to https://engine.lingo.dev).
52+
* - 'batchSize' with an integer between 1 and 250 to control items sent per request.
53+
* - 'idealBatchItemSize' with an integer between 1 and 2500 to cap words per request.
54+
* Invalid values trigger \InvalidArgumentException.
55+
*
56+
* @param array $config HTTP client credentials and optional batching overrides.
57+
*
58+
* @throws \InvalidArgumentException When the API key is missing or a value fails validation.
4959
*/
5060
public function __construct(array $config = [])
5161
{
@@ -280,16 +290,24 @@ private function _createId(): string
280290
}
281291

282292
/**
283-
* Localize a typical PHP array or object
284-
*
285-
* @param array $obj The object to be localized (strings will be extracted and translated)
286-
* @param array $params Localization parameters:
287-
* - sourceLocale: The source language code (e.g., 'en')
288-
* - targetLocale: The target language code (e.g., 'es')
289-
* - fast: Optional boolean to enable fast mode
290-
* @param callable|null $progressCallback Optional callback function to report progress (0-100)
291-
*
292-
* @return array A new object with the same structure but localized string values
293+
* Localize every string in a nested array while keeping the array structure.
294+
*
295+
* Require $params['targetLocale'] with the desired language code. Optionally
296+
* pass:
297+
* - 'sourceLocale' with the current language code (string or null).
298+
* - 'fast' with a boolean forwarded to the API.
299+
* - 'reference' with an array of supplemental data forwarded unchanged.
300+
* The optional callback receives (int $progress, array $chunk, array $localizedChunk)
301+
* for each batch the engine submits.
302+
*
303+
* @param array $obj Input data whose string entries should be localized.
304+
* @param array $params Request parameters for locales and API options.
305+
* @param callable|null $progressCallback Progress hook fired per batch.
306+
*
307+
* @return array Localized data mirroring the original structure.
308+
*
309+
* @throws \InvalidArgumentException When required params or reference data are invalid.
310+
* @throws \RuntimeException When the API rejects or fails to process the request.
293311
*/
294312
public function localizeObject(array $obj, array $params, ?callable $progressCallback = null): array
295313
{
@@ -305,16 +323,24 @@ public function localizeObject(array $obj, array $params, ?callable $progressCal
305323
}
306324

307325
/**
308-
* Localize a single text string
309-
*
310-
* @param string $text The text string to be localized
311-
* @param array $params Localization parameters:
312-
* - sourceLocale: The source language code (e.g., 'en')
313-
* - targetLocale: The target language code (e.g., 'es')
314-
* - fast: Optional boolean to enable fast mode
315-
* @param callable|null $progressCallback Optional callback function to report progress (0-100)
316-
*
317-
* @return string The localized text string
326+
* Translate a single string and return the localized text.
327+
*
328+
* Set $params['targetLocale'] to the destination language code. You may
329+
* also provide:
330+
* - 'sourceLocale' with the existing language code (string or null).
331+
* - 'fast' with a boolean forwarded to the API.
332+
* - 'reference' with an array of supplemental data forwarded unchanged.
333+
* The optional callback receives the completion percentage (0-100) for each
334+
* processed batch.
335+
*
336+
* @param string $text Source text to localize.
337+
* @param array $params Request parameters for locales and API options.
338+
* @param callable|null $progressCallback Progress hook fired with an integer percentage.
339+
*
340+
* @return string Localized text (empty string if the API omits the field).
341+
*
342+
* @throws \InvalidArgumentException When required params are missing or invalid.
343+
* @throws \RuntimeException When the API rejects or fails to process the request.
318344
*/
319345
public function localizeText(string $text, array $params, ?callable $progressCallback = null): string
320346
{
@@ -332,15 +358,20 @@ public function localizeText(string $text, array $params, ?callable $progressCal
332358
}
333359

334360
/**
335-
* Localize a text string to multiple target locales
336-
*
337-
* @param string $text The text string to be localized
338-
* @param array $params Localization parameters:
339-
* - sourceLocale: The source language code (e.g., 'en')
340-
* - targetLocales: An array of target language codes (e.g., ['es', 'fr'])
341-
* - fast: Optional boolean to enable fast mode
342-
*
343-
* @return array An array of localized text strings
361+
* Translate a string into several languages and return the results in order.
362+
*
363+
* Expect $params['sourceLocale'] with the language code of the input text
364+
* and $params['targetLocales'] with an array of destination language codes.
365+
* Optional 'fast' flags are forwarded to each {@see localizeText()} call.
366+
* Any failure from an individual request surfaces immediately.
367+
*
368+
* @param string $text Source text to localize.
369+
* @param array $params Request parameters describing the source and target languages.
370+
*
371+
* @return array List of localized strings matching the order of target locales.
372+
*
373+
* @throws \InvalidArgumentException When required params are missing or invalid.
374+
* @throws \RuntimeException When an individual localization request fails.
344375
*/
345376
public function batchLocalizeText(string $text, array $params): array
346377
{
@@ -367,16 +398,25 @@ public function batchLocalizeText(string $text, array $params): array
367398
}
368399

369400
/**
370-
* Localize a chat sequence while preserving speaker names
371-
*
372-
* @param array $chat Array of chat messages, each with 'name' and 'text' properties
373-
* @param array $params Localization parameters:
374-
* - sourceLocale: The source language code (e.g., 'en')
375-
* - targetLocale: The target language code (e.g., 'es')
376-
* - fast: Optional boolean to enable fast mode
377-
* @param callable|null $progressCallback Optional callback function to report progress (0-100)
378-
*
379-
* @return array Array of localized chat messages with preserved structure
401+
* Localize a chat transcript while keeping speaker names untouched.
402+
*
403+
* Each entry in $chat must provide 'name' and 'text'. Supply
404+
* $params['targetLocale'] with the destination language code. Optionally
405+
* pass:
406+
* - 'sourceLocale' with the current language code (string or null).
407+
* - 'fast' with a boolean forwarded to the API.
408+
* - 'reference' with an array of supplemental data forwarded unchanged.
409+
* The optional callback receives the completion percentage (0-100) for each
410+
* processed batch.
411+
*
412+
* @param array $chat Ordered list of chat message arrays with 'name' and 'text'.
413+
* @param array $params Request parameters for locales and API options.
414+
* @param callable|null $progressCallback Progress hook fired with an integer percentage.
415+
*
416+
* @return array Localized chat messages with original names preserved.
417+
*
418+
* @throws \InvalidArgumentException When chat entries or params are invalid.
419+
* @throws \RuntimeException When the API rejects or fails to process the request.
380420
*/
381421
public function localizeChat(array $chat, array $params, ?callable $progressCallback = null): array
382422
{
@@ -408,11 +448,17 @@ public function localizeChat(array $chat, array $params, ?callable $progressCall
408448
}
409449

410450
/**
411-
* Detect the language of a given text
412-
*
413-
* @param string $text The text to analyze
414-
*
415-
* @return string Locale code (e.g., 'en', 'es', 'fr')
451+
* Ask the API to identify the locale of the provided text.
452+
*
453+
* Whitespace-only strings are rejected. On success the API's 'locale'
454+
* field is returned directly.
455+
*
456+
* @param string $text Text whose locale should be recognised.
457+
*
458+
* @return string Locale code provided by the API.
459+
*
460+
* @throws \InvalidArgumentException When the input text is blank after trimming.
461+
* @throws \RuntimeException When the API response is invalid or the request fails.
416462
*/
417463
public function recognizeLocale(string $text): string
418464
{

‎test-all-methods.php‎

Lines changed: 11 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -24,6 +24,17 @@
2424
"apiKey" => $apiKey,
2525
]);
2626

27+
/**
28+
* Execute a CLI test callback, reporting success or failure to stdout.
29+
*
30+
* Prints the section header, runs the callback, dumps the JSON-encoded result
31+
* when successful, or surfaces exception details (including HTTP responses).
32+
*
33+
* @param string $name Human-readable test name displayed in logs.
34+
* @param callable $callback Zero-argument function returning the test result.
35+
*
36+
* @return bool True on success, false on failure.
37+
*/
2738
function runTest($name, $callback) {
2839
echo "\n=== Testing $name ===\n";
2940
try {

0 commit comments

Comments
 (0)