Skip to content

Commit 58d09ff

Browse files
davidturnbulldavidturnbull
committed
docs: update
1 parent b3f4001 commit 58d09ff

File tree

1 file changed

+53
-85
lines changed

1 file changed

+53
-85
lines changed

‎src/LingoDotDevEngine.php‎

Lines changed: 53 additions & 85 deletions
Original file line numberDiff line numberDiff line change
@@ -23,17 +23,11 @@
2323
* progress reporting, and surfacing validation or transport errors.
2424
*
2525
* Example (basic setup):
26-
* <pre><code class="language-php">
27-
* <?php
28-
* $engine = new LingoDotDevEngine(['apiKey' => $_ENV['LINGODOTDEV_API_KEY']]);
29-
* </code></pre>
26+
* $engine = new LingoDotDevEngine(['apiKey' => $_ENV['LINGODOTDEV_API_KEY']]);
3027
*
3128
* Example (Laravel integration):
32-
* <pre><code class="language-php">
33-
* <?php
34-
* $engine = new LingoDotDevEngine(['apiKey' => config('services.lingodotdev.api_key')]);
35-
* $engine->localizeText($request->message, ['sourceLocale' => 'en', 'targetLocale' => 'es']);
36-
* </code></pre>
29+
* $engine = new LingoDotDevEngine(['apiKey' => config('services.lingodotdev.api_key')]);
30+
* $engine->localizeText($request->message, ['sourceLocale' => 'en', 'targetLocale' => 'es']);
3731
*
3832
* @category Localization
3933
* @package Lingodotdev\Sdk
@@ -46,7 +40,7 @@ class LingoDotDevEngine
4640
/**
4741
* Configuration options for the Engine.
4842
*
49-
* @var array<string, mixed>
43+
* @var array{apiKey: string, apiUrl: string, batchSize: int, idealBatchItemSize: int}
5044
*/
5145
protected $config;
5246

@@ -60,21 +54,18 @@ class LingoDotDevEngine
6054
/**
6155
* Build an engine with your API key and optional batching limits.
6256
*
63-
* @param array{apiKey:string,apiUrl?:string,batchSize?:int,idealBatchItemSize?:int} $config Configuration options:
57+
* @param array{apiKey: string, apiUrl?: string, batchSize?: int, idealBatchItemSize?: int} $config Configuration options:
6458
* - 'apiKey' (string, required): Your API token
6559
* - 'apiUrl' (string): API base URL (default: https://engine.lingo.dev)
6660
* - 'batchSize' (int): Records per request, 1-250 (default: 25)
6761
* - 'idealBatchItemSize' (int): Max words per request, 1-2500 (default: 250)
6862
*
6963
* Example:
70-
* <pre><code class="language-php">
71-
* <?php
72-
* $engine = new LingoDotDevEngine([
73-
* 'apiKey' => $_ENV['LINGODOTDEV_API_KEY'],
74-
* 'batchSize' => 100,
75-
* 'idealBatchItemSize' => 1000,
76-
* ]);
77-
* </code></pre>
64+
* $engine = new LingoDotDevEngine([
65+
* 'apiKey' => $_ENV['LINGODOTDEV_API_KEY'],
66+
* 'batchSize' => 100,
67+
* 'idealBatchItemSize' => 1000,
68+
* ]);
7869
*
7970
* @throws \InvalidArgumentException When API key is missing or values fail validation
8071
*/
@@ -119,7 +110,7 @@ public function __construct(array $config = [])
119110
* Localize content using the Lingo.dev API.
120111
*
121112
* @param array<string, mixed> $payload Content to translate, structured as key-value pairs
122-
* @param array{targetLocale:string,sourceLocale?:string|null,fast?:bool,reference?:array<string, mixed>|null} $params Translation configuration options:
113+
* @param array{targetLocale: string, sourceLocale?: string|null, fast?: bool, reference?: array<string, mixed>|null} $params Translation configuration options:
123114
* - 'targetLocale' (string, required): Language code to translate into (e.g., 'es', 'fr')
124115
* - 'sourceLocale' (string|null): Language code of original text, null for auto-detection
125116
* - 'fast' (bool): Trade translation quality for speed
@@ -179,7 +170,9 @@ protected function localizeRaw(array $payload, array $params, ?callable $progres
179170
*
180171
* @param string|null $sourceLocale Language code of the original text (e.g., 'en', 'es'), null for auto-detection
181172
* @param string $targetLocale Language code to translate into (e.g., 'fr', 'de')
182-
* @param array{data:array<string, mixed>,reference?:array<string, mixed>|null} $payload Content chunk with optional reference data for context
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
183176
* @param string $workflowId Unique identifier for tracking related translation requests
184177
* @param bool $fast Enable faster translation at potential quality tradeoff
185178
*
@@ -322,7 +315,7 @@ private function _createId(): string
322315
* Localize every string in a nested array while keeping its shape intact.
323316
*
324317
* @param array<string, mixed> $obj Nested data structure containing text to translate
325-
* @param array{targetLocale:string,sourceLocale?:string|null,fast?:bool,reference?:array<string, mixed>|null} $params Translation options controlling locale, speed, and contextual reference data:
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:
326319
* - 'targetLocale' (string, required): Language code to translate into (e.g., 'es', 'fr')
327320
* - 'sourceLocale' (string|null): Language code of original text, null for auto-detection
328321
* - 'fast' (bool): Trade translation quality for speed
@@ -331,13 +324,10 @@ private function _createId(): string
331324
*
332325
* @return array<string, mixed> Translated data preserving original structure and non-text values
333326
*
334-
* @example Object translation
335-
* <pre><code class="language-php">
336-
* <?php
337-
* $content = ['greeting' => 'Hello'];
338-
* $engine = new LingoDotDevEngine(['apiKey' => $_ENV['LINGODOTDEV_API_KEY']]);
339-
* $engine->localizeObject($content, ['sourceLocale' => 'en', 'targetLocale' => 'fr']);
340-
* </code></pre>
327+
* Example:
328+
* $content = ['greeting' => 'Hello'];
329+
* $engine = new LingoDotDevEngine(['apiKey' => $_ENV['LINGODOTDEV_API_KEY']]);
330+
* $engine->localizeObject($content, ['sourceLocale' => 'en', 'targetLocale' => 'fr']);
341331
*
342332
* @throws \InvalidArgumentException When required params or reference data are invalid
343333
* @throws \RuntimeException When API rejects or fails to process the request
@@ -359,7 +349,7 @@ public function localizeObject(array $obj, array $params, ?callable $progressCal
359349
* Localize a single string and return the translated text.
360350
*
361351
* @param string $text Text content to translate
362-
* @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:
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:
363353
* - 'targetLocale' (string, required): Language code to translate into (e.g., 'es', 'fr')
364354
* - 'sourceLocale' (string|null): Language code of original text, null for auto-detection
365355
* - 'fast' (bool): Trade translation quality for speed
@@ -368,32 +358,19 @@ public function localizeObject(array $obj, array $params, ?callable $progressCal
368358
*
369359
* @return string Translated text, or empty string if translation unavailable
370360
*
371-
* @example Text translation
372-
* <pre><code class="language-php">
373-
* <?php
374-
* $engine = new LingoDotDevEngine(['apiKey' => $_ENV['LINGODOTDEV_API_KEY']]);
375-
* echo $engine->localizeText('Hello, world!', ['sourceLocale' => 'en', 'targetLocale' => 'es']);
376-
* </code></pre>
377-
*
378-
* @example Progress tracking
379-
* <pre><code class="language-php">
380-
* <?php
381-
* $engine = new LingoDotDevEngine(['apiKey' => $_ENV['LINGODOTDEV_API_KEY']]);
382-
* $engine->localizeText(
383-
* 'This is a very long text that needs translation...',
384-
* ['sourceLocale' => 'en', 'targetLocale' => 'es'],
385-
* function (int $progress): void {
386-
* echo 'Translation progress: ' . $progress . "%\n";
387-
* }
388-
* );
389-
* </code></pre>
390-
*
391-
* @example Automatic language detection
392-
* <pre><code class="language-php">
393-
* <?php
394-
* $engine = new LingoDotDevEngine(['apiKey' => $_ENV['LINGODOTDEV_API_KEY']]);
395-
* echo $engine->localizeText('Bonjour le monde', ['sourceLocale' => null, 'targetLocale' => 'en']);
396-
* </code></pre>
361+
* Examples:
362+
* $engine = new LingoDotDevEngine(['apiKey' => $_ENV['LINGODOTDEV_API_KEY']]);
363+
* $engine->localizeText('Hello, world!', ['sourceLocale' => 'en', 'targetLocale' => 'es']);
364+
*
365+
* $engine->localizeText(
366+
* 'This is a very long text that needs translation...',
367+
* ['sourceLocale' => 'en', 'targetLocale' => 'es'],
368+
* function (int $progress): void {
369+
* echo 'Translation progress: ' . $progress . "%\n";
370+
* }
371+
* );
372+
*
373+
* $engine->localizeText('Bonjour le monde', ['sourceLocale' => null, 'targetLocale' => 'en']);
397374
*
398375
* @throws \InvalidArgumentException When required params are missing or invalid
399376
* @throws \RuntimeException When API rejects or fails to process the request
@@ -417,22 +394,19 @@ public function localizeText(string $text, array $params, ?callable $progressCal
417394
* Localize a string into multiple languages and return texts in order.
418395
*
419396
* @param string $text Text content to translate into multiple languages
420-
* @param array{sourceLocale:string,targetLocales:array<int,string>,fast?:bool} $params Batch translation options shared by all target locales:
397+
* @param array{sourceLocale: string, targetLocales: string[], fast?: bool} $params Batch translation options shared by all target locales:
421398
* - 'sourceLocale' (string, required): Language code of the original text (e.g., 'en')
422399
* - 'targetLocales' (string[], required): Array of language codes to translate into (e.g., ['es', 'fr', 'de'])
423400
* - 'fast' (bool): Trade translation quality for speed
424401
*
425402
* @return string[] Array of translated texts in same order as targetLocales parameter
426403
*
427-
* @example Batch translation to multiple languages
428-
* <pre><code class="language-php">
429-
* <?php
430-
* $engine = new LingoDotDevEngine(['apiKey' => $_ENV['LINGODOTDEV_API_KEY']]);
431-
* $results = $engine->batchLocalizeText('Hello, world!', [
432-
* 'sourceLocale' => 'en',
433-
* 'targetLocales' => ['es', 'fr', 'de'],
434-
* ]);
435-
* </code></pre>
404+
* Example:
405+
* $engine = new LingoDotDevEngine(['apiKey' => $_ENV['LINGODOTDEV_API_KEY']]);
406+
* $engine->batchLocalizeText('Hello, world!', [
407+
* 'sourceLocale' => 'en',
408+
* 'targetLocales' => ['es', 'fr', 'de'],
409+
* ]);
436410
*
437411
* @throws \InvalidArgumentException When required params are missing or invalid
438412
* @throws \RuntimeException When an individual localization request fails
@@ -464,28 +438,25 @@ public function batchLocalizeText(string $text, array $params): array
464438
/**
465439
* Localize a chat transcript while preserving speaker names.
466440
*
467-
* @param array<int, array{name:string,text:string}> $chat Conversation history with speaker names and their messages. Each entry must include:
441+
* @param array<int, array{name: string, text: string}> $chat Conversation history with speaker names and their messages. Each entry must include:
468442
* - 'name' (string): Speaker label to preserve
469443
* - 'text' (string): Message content to translate
470-
* @param array{targetLocale:string,sourceLocale?:string|null,fast?:bool,reference?:array<string, mixed>|null} $params Chat translation options defining locale behavior and context:
444+
* @param array{targetLocale: string, sourceLocale?: string|null, fast?: bool, reference?: array<string, mixed>|null} $params Chat translation options defining locale behavior and context:
471445
* - 'targetLocale' (string, required): Language code to translate messages into (e.g., 'es', 'fr')
472446
* - 'sourceLocale' (string|null): Language code of original messages, null for auto-detection
473447
* - 'fast' (bool): Trade translation quality for speed
474448
* - 'reference' (array<string, mixed>|null): Context data or glossary terms to guide translation
475449
* @param callable|null $progressCallback Called with completion percentage (0-100) during processing
476450
*
477-
* @return array<int, array<string, string>> Translated messages keeping original speaker names unchanged
451+
* @return array<int, array{name: string, text: string}> Translated messages keeping original speaker names unchanged
478452
*
479-
* @example Chat translation
480-
* <pre><code class="language-php">
481-
* <?php
482-
* $engine = new LingoDotDevEngine(['apiKey' => $_ENV['LINGODOTDEV_API_KEY']]);
483-
* $conversation = [
484-
* ['name' => 'Alice', 'text' => 'Hello, how are you?'],
485-
* ['name' => 'Bob', 'text' => 'I am fine, thank you!']
486-
* ];
487-
* $engine->localizeChat($conversation, ['sourceLocale' => 'en', 'targetLocale' => 'de']);
488-
* </code></pre>
453+
* Example:
454+
* $conversation = [
455+
* ['name' => 'Alice', 'text' => 'Hello, how are you?'],
456+
* ['name' => 'Bob', 'text' => 'I am fine, thank you!'],
457+
* ];
458+
* $engine = new LingoDotDevEngine(['apiKey' => $_ENV['LINGODOTDEV_API_KEY']]);
459+
* $engine->localizeChat($conversation, ['sourceLocale' => 'en', 'targetLocale' => 'de']);
489460
*
490461
* @throws \InvalidArgumentException When chat entries or params are invalid
491462
* @throws \RuntimeException When API rejects or fails to process the request
@@ -526,12 +497,9 @@ public function localizeChat(array $chat, array $params, ?callable $progressCall
526497
*
527498
* @return string ISO language code detected by the API (e.g., 'en', 'es', 'zh')
528499
*
529-
* @example Language detection
530-
* <pre><code class="language-php">
531-
* <?php
532-
* $engine = new LingoDotDevEngine(['apiKey' => $_ENV['LINGODOTDEV_API_KEY']]);
533-
* echo $engine->recognizeLocale('Bonjour le monde');
534-
* </code></pre>
500+
* Example:
501+
* $engine = new LingoDotDevEngine(['apiKey' => $_ENV['LINGODOTDEV_API_KEY']]);
502+
* $engine->recognizeLocale('Bonjour le monde');
535503
*
536504
* @throws \InvalidArgumentException When input text is blank after trimming
537505
* @throws \RuntimeException When API response is invalid or request fails

0 commit comments

Comments
 (0)