Skip to content

Commit 6282355

Browse files
davidturnbulldavidturnbull
committed
docs: update
1 parent 8d7f3ba commit 6282355

File tree

1 file changed

+52
-79
lines changed

1 file changed

+52
-79
lines changed

‎src/LingoDotDevEngine.php‎

Lines changed: 52 additions & 79 deletions
Original file line numberDiff line numberDiff line change
@@ -54,20 +54,16 @@ class LingoDotDevEngine
5454
/**
5555
* Build an engine with your API key and optional batching limits.
5656
*
57-
* @param array{apiKey: string, apiUrl?: string, batchSize?: int, idealBatchItemSize?: int} $config Configuration options:
58-
* - 'apiKey' (string, required): Your API token
59-
* - 'apiUrl' (string): API base URL (default: https://engine.lingo.dev)
60-
* - 'batchSize' (int): Records per request, 1-250 (default: 25)
61-
* - 'idealBatchItemSize' (int): Max words per request, 1-2500 (default: 250)
62-
*
6357
* Example:
6458
* $engine = new LingoDotDevEngine([
6559
* 'apiKey' => $_ENV['LINGODOTDEV_API_KEY'],
6660
* 'batchSize' => 100,
6761
* 'idealBatchItemSize' => 1000,
6862
* ]);
6963
*
70-
* @throws \InvalidArgumentException When API key is missing or values fail validation
64+
* @param array{apiKey: string, apiUrl?: string, batchSize?: int, idealBatchItemSize?: int} $config Configuration options
65+
*
66+
* @throws \InvalidArgumentException API key missing or values invalid
7167
*/
7268
public function __construct(array $config = [])
7369
{
@@ -109,15 +105,11 @@ public function __construct(array $config = [])
109105
/**
110106
* Localize content using the Lingo.dev API.
111107
*
112-
* @param array<string, mixed> $payload Content to translate, structured as key-value pairs
113-
* @param array{targetLocale: string, sourceLocale?: string|null, fast?: bool, reference?: array<string, mixed>|null} $params Translation configuration options:
114-
* - 'targetLocale' (string, required): Language code to translate into (e.g., 'es', 'fr')
115-
* - 'sourceLocale' (string|null): Language code of original text, null for auto-detection
116-
* - 'fast' (bool): Trade translation quality for speed
117-
* - 'reference' (array<string, mixed>|null): Context data or glossary terms to guide translation
118-
* @param callable|null $progressCallback Callback invoked with completion percentage (0-100), current chunk, and processed chunk
108+
* @param array<string, mixed> $payload Content to translate
109+
* @param array{targetLocale: string, sourceLocale?: string|null, fast?: bool, reference?: array<string, mixed>|null} $params Translation configuration
110+
* @param callable|null $progressCallback Progress callback (0-100%, chunk, result)
119111
*
120-
* @return array<string, mixed> Translated content maintaining original structure
112+
* @return array<string, mixed> Translated content
121113
*
122114
* @internal
123115
*/
@@ -168,18 +160,16 @@ protected function localizeRaw(array $payload, array $params, ?callable $progres
168160
/**
169161
* Localize a single chunk of content.
170162
*
171-
* @param string|null $sourceLocale Language code of the original text (e.g., 'en', 'es'), null for auto-detection
172-
* @param string $targetLocale Language code to translate into (e.g., 'fr', 'de')
173-
* @param array{data: array<string, mixed>, reference?: array<string, mixed>|null} $payload Content chunk with optional reference data for context. Expected keys:
174-
* - 'data' (array<string, mixed>): Chunk data submitted for translation
175-
* - 'reference' (array<string, mixed>|null): Context data or glossary terms to guide translation
176-
* @param string $workflowId Unique identifier for tracking related translation requests
177-
* @param bool $fast Enable faster translation at potential quality tradeoff
163+
* @param string|null $sourceLocale Source language code or null for auto-detect
164+
* @param string $targetLocale Target language code
165+
* @param array{data: array<string, mixed>, reference?: array<string, mixed>|null} $payload Content chunk with optional reference
166+
* @param string $workflowId Workflow tracking ID
167+
* @param bool $fast Fast mode flag
178168
*
179-
* @return array<string, mixed> Translated chunk maintaining original structure
169+
* @return array<string, mixed> Translated chunk
180170
*
181-
* @throws \InvalidArgumentException When reference is not an array
182-
* @throws \RuntimeException When API request fails
171+
* @throws \InvalidArgumentException Invalid reference format
172+
* @throws \RuntimeException API request failure
183173
*/
184174
private function _localizeChunk(?string $sourceLocale, string $targetLocale, array $payload, string $workflowId, bool $fast): array
185175
{
@@ -314,23 +304,19 @@ private function _createId(): string
314304
/**
315305
* Localize every string in a nested array while keeping its shape intact.
316306
*
317-
* @param array<string, mixed> $obj Nested data structure containing text to translate
318-
* @param array{targetLocale: string, sourceLocale?: string|null, fast?: bool, reference?: array<string, mixed>|null} $params Translation options controlling locale, speed, and contextual reference data:
319-
* - 'targetLocale' (string, required): Language code to translate into (e.g., 'es', 'fr')
320-
* - 'sourceLocale' (string|null): Language code of original text, null for auto-detection
321-
* - 'fast' (bool): Trade translation quality for speed
322-
* - 'reference' (array<string, mixed>|null): Context data or glossary terms to guide translation
323-
* @param callable|null $progressCallback Invoked per batch with (percentage complete, current batch, translated batch)
324-
*
325-
* @return array<string, mixed> Translated data preserving original structure and non-text values
326-
*
327307
* Example:
328308
* $content = ['greeting' => 'Hello'];
329309
* $engine = new LingoDotDevEngine(['apiKey' => $_ENV['LINGODOTDEV_API_KEY']]);
330310
* $engine->localizeObject($content, ['sourceLocale' => 'en', 'targetLocale' => 'fr']);
331311
*
332-
* @throws \InvalidArgumentException When required params or reference data are invalid
333-
* @throws \RuntimeException When API rejects or fails to process the request
312+
* @param array<string, mixed> $obj Nested data structure to translate
313+
* @param array{targetLocale: string, sourceLocale?: string|null, fast?: bool, reference?: array<string, mixed>|null} $params Translation options
314+
* @param callable|null $progressCallback Progress callback (%, batch, result)
315+
*
316+
* @return array<string, mixed> Translated data preserving structure
317+
*
318+
* @throws \InvalidArgumentException Invalid parameters or reference
319+
* @throws \RuntimeException API request failure
334320
*/
335321
public function localizeObject(array $obj, array $params, ?callable $progressCallback = null): array
336322
{
@@ -348,16 +334,6 @@ public function localizeObject(array $obj, array $params, ?callable $progressCal
348334
/**
349335
* Localize a single string and return the translated text.
350336
*
351-
* @param string $text Text content to translate
352-
* @param array{targetLocale: string, sourceLocale?: string|null, fast?: bool, reference?: array<string, mixed>|null} $params Translation options such as locale hints, speed preference, and contextual references:
353-
* - 'targetLocale' (string, required): Language code to translate into (e.g., 'es', 'fr')
354-
* - 'sourceLocale' (string|null): Language code of original text, null for auto-detection
355-
* - 'fast' (bool): Trade translation quality for speed
356-
* - 'reference' (array<string, mixed>|null): Context data or glossary terms to guide translation
357-
* @param callable|null $progressCallback Called with completion percentage (0-100) during processing
358-
*
359-
* @return string Translated text, or empty string if translation unavailable
360-
*
361337
* Examples:
362338
* $engine = new LingoDotDevEngine(['apiKey' => $_ENV['LINGODOTDEV_API_KEY']]);
363339
* $engine->localizeText('Hello, world!', ['sourceLocale' => 'en', 'targetLocale' => 'es']);
@@ -372,8 +348,14 @@ public function localizeObject(array $obj, array $params, ?callable $progressCal
372348
*
373349
* $engine->localizeText('Bonjour le monde', ['sourceLocale' => null, 'targetLocale' => 'en']);
374350
*
375-
* @throws \InvalidArgumentException When required params are missing or invalid
376-
* @throws \RuntimeException When API rejects or fails to process the request
351+
* @param string $text Text to translate
352+
* @param array{targetLocale: string, sourceLocale?: string|null, fast?: bool, reference?: array<string, mixed>|null} $params Translation options
353+
* @param callable|null $progressCallback Progress callback (0-100%)
354+
*
355+
* @return string Translated text or empty string
356+
*
357+
* @throws \InvalidArgumentException Missing or invalid parameters
358+
* @throws \RuntimeException API request failure
377359
*/
378360
public function localizeText(string $text, array $params, ?callable $progressCallback = null): string
379361
{
@@ -393,23 +375,20 @@ public function localizeText(string $text, array $params, ?callable $progressCal
393375
/**
394376
* Localize a string into multiple languages and return texts in order.
395377
*
396-
* @param string $text Text content to translate into multiple languages
397-
* @param array{sourceLocale: string, targetLocales: string[], fast?: bool} $params Batch translation options shared by all target locales:
398-
* - 'sourceLocale' (string, required): Language code of the original text (e.g., 'en')
399-
* - 'targetLocales' (string[], required): Array of language codes to translate into (e.g., ['es', 'fr', 'de'])
400-
* - 'fast' (bool): Trade translation quality for speed
401-
*
402-
* @return string[] Array of translated texts in same order as targetLocales parameter
403-
*
404378
* Example:
405379
* $engine = new LingoDotDevEngine(['apiKey' => $_ENV['LINGODOTDEV_API_KEY']]);
406380
* $engine->batchLocalizeText('Hello, world!', [
407381
* 'sourceLocale' => 'en',
408382
* 'targetLocales' => ['es', 'fr', 'de'],
409383
* ]);
410384
*
411-
* @throws \InvalidArgumentException When required params are missing or invalid
412-
* @throws \RuntimeException When an individual localization request fails
385+
* @param string $text Text to translate
386+
* @param array{sourceLocale: string, targetLocales: string[], fast?: bool} $params Batch translation options
387+
*
388+
* @return string[] Translated texts in targetLocales order
389+
*
390+
* @throws \InvalidArgumentException Missing or invalid parameters
391+
* @throws \RuntimeException Individual request failure
413392
*/
414393
public function batchLocalizeText(string $text, array $params): array
415394
{
@@ -438,18 +417,6 @@ public function batchLocalizeText(string $text, array $params): array
438417
/**
439418
* Localize a chat transcript while preserving speaker names.
440419
*
441-
* @param array<int, array{name: string, text: string}> $chat Conversation history with speaker names and their messages. Each entry must include:
442-
* - 'name' (string): Speaker label to preserve
443-
* - 'text' (string): Message content to translate
444-
* @param array{targetLocale: string, sourceLocale?: string|null, fast?: bool, reference?: array<string, mixed>|null} $params Chat translation options defining locale behavior and context:
445-
* - 'targetLocale' (string, required): Language code to translate messages into (e.g., 'es', 'fr')
446-
* - 'sourceLocale' (string|null): Language code of original messages, null for auto-detection
447-
* - 'fast' (bool): Trade translation quality for speed
448-
* - 'reference' (array<string, mixed>|null): Context data or glossary terms to guide translation
449-
* @param callable|null $progressCallback Called with completion percentage (0-100) during processing
450-
*
451-
* @return array<int, array{name: string, text: string}> Translated messages keeping original speaker names unchanged
452-
*
453420
* Example:
454421
* $conversation = [
455422
* ['name' => 'Alice', 'text' => 'Hello, how are you?'],
@@ -458,8 +425,14 @@ public function batchLocalizeText(string $text, array $params): array
458425
* $engine = new LingoDotDevEngine(['apiKey' => $_ENV['LINGODOTDEV_API_KEY']]);
459426
* $engine->localizeChat($conversation, ['sourceLocale' => 'en', 'targetLocale' => 'de']);
460427
*
461-
* @throws \InvalidArgumentException When chat entries or params are invalid
462-
* @throws \RuntimeException When API rejects or fails to process the request
428+
* @param array<int, array{name: string, text: string}> $chat Conversation with names and messages
429+
* @param array{targetLocale: string, sourceLocale?: string|null, fast?: bool, reference?: array<string, mixed>|null} $params Translation options
430+
* @param callable|null $progressCallback Progress callback (0-100%)
431+
*
432+
* @return array<int, array{name: string, text: string}> Translated chat preserving names
433+
*
434+
* @throws \InvalidArgumentException Invalid chat entries or parameters
435+
* @throws \RuntimeException API request failure
463436
*/
464437
public function localizeChat(array $chat, array $params, ?callable $progressCallback = null): array
465438
{
@@ -493,16 +466,16 @@ public function localizeChat(array $chat, array $params, ?callable $progressCall
493466
/**
494467
* Identify the locale of the provided text.
495468
*
496-
* @param string $text Sample text for language detection (longer text improves accuracy)
497-
*
498-
* @return string ISO language code detected by the API (e.g., 'en', 'es', 'zh')
499-
*
500469
* Example:
501470
* $engine = new LingoDotDevEngine(['apiKey' => $_ENV['LINGODOTDEV_API_KEY']]);
502471
* $engine->recognizeLocale('Bonjour le monde');
503472
*
504-
* @throws \InvalidArgumentException When input text is blank after trimming
505-
* @throws \RuntimeException When API response is invalid or request fails
473+
* @param string $text Sample text for language detection
474+
*
475+
* @return string ISO language code (e.g., 'en', 'es', 'zh')
476+
*
477+
* @throws \InvalidArgumentException Empty text provided
478+
* @throws \RuntimeException Invalid API response or request failure
506479
*/
507480
public function recognizeLocale(string $text): string
508481
{

0 commit comments

Comments
 (0)