Skip to content

Commit 1b5fa78

Browse files
davidturnbulldavidturnbull
committed
docs: update
1 parent 953cd42 commit 1b5fa78

File tree

1 file changed

+32
-67
lines changed

1 file changed

+32
-67
lines changed

‎src/LingoDotDevEngine.php‎

Lines changed: 32 additions & 67 deletions
Original file line numberDiff line numberDiff line change
@@ -23,50 +23,23 @@
2323
* progress reporting, and surfacing validation or transport errors.
2424
*
2525
* Example (basic setup):
26-
* @code
26+
* <pre><code class="language-php">
2727
* <?php
2828
* $engine = new LingoDotDevEngine(['apiKey' => $_ENV['LINGODOTDEV_API_KEY']]);
29-
* @endcode
29+
* </code></pre>
3030
*
3131
* Example (Laravel integration):
32-
* @code
32+
* <pre><code class="language-php">
3333
* <?php
3434
* $engine = new LingoDotDevEngine(['apiKey' => config('services.lingodotdev.api_key')]);
3535
* $engine->localizeText($request->message, ['sourceLocale' => 'en', 'targetLocale' => 'es']);
36-
* @endcode
36+
* </code></pre>
3737
*
3838
* @category Localization
3939
* @package Lingodotdev\Sdk
4040
* @author Lingo.dev Team <hi@lingo.dev>
4141
* @license MIT https://opensource.org/licenses/MIT
4242
* @link https://lingo.dev
43-
*
44-
* @phpstan-type EngineConfig array{
45-
* apiKey: string,
46-
* apiUrl?: string,
47-
* batchSize?: positive-int,
48-
* idealBatchItemSize?: positive-int
49-
* }
50-
* @phpstan-type LocalizeParams array{
51-
* targetLocale: string,
52-
* sourceLocale?: string|null,
53-
* fast?: bool,
54-
* reference?: array<string, mixed>|null
55-
* }
56-
* @phpstan-type BatchLocalizeParams array{
57-
* sourceLocale: string,
58-
* targetLocales: array<int, string>,
59-
* fast?: bool
60-
* }
61-
* @phpstan-type ChatMessage array{
62-
* name: string,
63-
* text: string
64-
* }
65-
* @phpstan-type ChatTranscript array<int, ChatMessage>
66-
* @phpstan-type ChunkPayload array{
67-
* data: array<string, mixed>,
68-
* reference?: array<string, mixed>|null
69-
* }
7043
*/
7144
class LingoDotDevEngine
7245
{
@@ -87,22 +60,21 @@ class LingoDotDevEngine
8760
/**
8861
* Build an engine with your API key and optional batching limits.
8962
*
90-
* @param array<string, mixed> $config Configuration options:
63+
* @param array{apiKey:string,apiUrl?:string,batchSize?:int,idealBatchItemSize?:int} $config Configuration options:
9164
* - 'apiKey' (string, required): Your API token
9265
* - 'apiUrl' (string): API base URL (default: https://engine.lingo.dev)
9366
* - 'batchSize' (int): Records per request, 1-250 (default: 25)
9467
* - 'idealBatchItemSize' (int): Max words per request, 1-2500 (default: 250)
95-
* @phpstan-param EngineConfig $config
9668
*
9769
* Example:
98-
* @code
70+
* <pre><code class="language-php">
9971
* <?php
10072
* $engine = new LingoDotDevEngine([
10173
* 'apiKey' => $_ENV['LINGODOTDEV_API_KEY'],
10274
* 'batchSize' => 100,
10375
* 'idealBatchItemSize' => 1000,
10476
* ]);
105-
* @endcode
77+
* </code></pre>
10678
*
10779
* @throws \InvalidArgumentException When API key is missing or values fail validation
10880
*/
@@ -147,13 +119,12 @@ public function __construct(array $config = [])
147119
* Localize content using the Lingo.dev API.
148120
*
149121
* @param array<string, mixed> $payload Content to translate, structured as key-value pairs
150-
* @param array<string, mixed> $params Translation configuration options:
122+
* @param array{targetLocale:string,sourceLocale?:string|null,fast?:bool,reference?:array<string, mixed>|null} $params Translation configuration options:
151123
* - 'targetLocale' (string, required): Language code to translate into (e.g., 'es', 'fr')
152124
* - 'sourceLocale' (string|null): Language code of original text, null for auto-detection
153125
* - 'fast' (bool): Trade translation quality for speed
154126
* - 'reference' (array<string, mixed>|null): Context data or glossary terms to guide translation
155-
* @phpstan-param LocalizeParams $params
156-
* @param (callable(int, array<string, mixed>, array<string, mixed>): void)|null $progressCallback Callback invoked with completion percentage (0-100), current chunk, and processed chunk
127+
* @param callable|null $progressCallback Callback invoked with completion percentage (0-100), current chunk, and processed chunk
157128
*
158129
* @return array<string, mixed> Translated content maintaining original structure
159130
*
@@ -208,8 +179,7 @@ protected function localizeRaw(array $payload, array $params, ?callable $progres
208179
*
209180
* @param string|null $sourceLocale Language code of the original text (e.g., 'en', 'es'), null for auto-detection
210181
* @param string $targetLocale Language code to translate into (e.g., 'fr', 'de')
211-
* @param array<string, mixed> $payload Content chunk with optional reference data for context
212-
* @phpstan-param ChunkPayload $payload
182+
* @param array{data:array<string, mixed>,reference?:array<string, mixed>|null} $payload Content chunk with optional reference data for context
213183
* @param string $workflowId Unique identifier for tracking related translation requests
214184
* @param bool $fast Enable faster translation at potential quality tradeoff
215185
*
@@ -352,23 +322,22 @@ private function _createId(): string
352322
* Localize every string in a nested array while keeping its shape intact.
353323
*
354324
* @param array<string, mixed> $obj Nested data structure containing text to translate
355-
* @param array<string, mixed> $params Translation options controlling locale, speed, and contextual reference data:
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:
356326
* - 'targetLocale' (string, required): Language code to translate into (e.g., 'es', 'fr')
357327
* - 'sourceLocale' (string|null): Language code of original text, null for auto-detection
358328
* - 'fast' (bool): Trade translation quality for speed
359329
* - 'reference' (array<string, mixed>|null): Context data or glossary terms to guide translation
360-
* @phpstan-param LocalizeParams $params
361-
* @param (callable(int, array<string, mixed>, array<string, mixed>): void)|null $progressCallback Invoked per batch with (percentage complete, current batch, translated batch)
330+
* @param callable|null $progressCallback Invoked per batch with (percentage complete, current batch, translated batch)
362331
*
363332
* @return array<string, mixed> Translated data preserving original structure and non-text values
364333
*
365334
* @example Object translation
366-
* @code
335+
* <pre><code class="language-php">
367336
* <?php
368337
* $content = ['greeting' => 'Hello'];
369338
* $engine = new LingoDotDevEngine(['apiKey' => $_ENV['LINGODOTDEV_API_KEY']]);
370339
* $engine->localizeObject($content, ['sourceLocale' => 'en', 'targetLocale' => 'fr']);
371-
* @endcode
340+
* </code></pre>
372341
*
373342
* @throws \InvalidArgumentException When required params or reference data are invalid
374343
* @throws \RuntimeException When API rejects or fails to process the request
@@ -390,25 +359,24 @@ public function localizeObject(array $obj, array $params, ?callable $progressCal
390359
* Localize a single string and return the translated text.
391360
*
392361
* @param string $text Text content to translate
393-
* @param array<string, mixed> $params Translation options such as locale hints, speed preference, and contextual references:
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:
394363
* - 'targetLocale' (string, required): Language code to translate into (e.g., 'es', 'fr')
395364
* - 'sourceLocale' (string|null): Language code of original text, null for auto-detection
396365
* - 'fast' (bool): Trade translation quality for speed
397366
* - 'reference' (array<string, mixed>|null): Context data or glossary terms to guide translation
398-
* @phpstan-param LocalizeParams $params
399-
* @param (callable(int): void)|null $progressCallback Called with completion percentage (0-100) during processing
367+
* @param callable|null $progressCallback Called with completion percentage (0-100) during processing
400368
*
401369
* @return string Translated text, or empty string if translation unavailable
402370
*
403371
* @example Text translation
404-
* @code
372+
* <pre><code class="language-php">
405373
* <?php
406374
* $engine = new LingoDotDevEngine(['apiKey' => $_ENV['LINGODOTDEV_API_KEY']]);
407375
* echo $engine->localizeText('Hello, world!', ['sourceLocale' => 'en', 'targetLocale' => 'es']);
408-
* @endcode
376+
* </code></pre>
409377
*
410378
* @example Progress tracking
411-
* @code
379+
* <pre><code class="language-php">
412380
* <?php
413381
* $engine = new LingoDotDevEngine(['apiKey' => $_ENV['LINGODOTDEV_API_KEY']]);
414382
* $engine->localizeText(
@@ -418,14 +386,14 @@ public function localizeObject(array $obj, array $params, ?callable $progressCal
418386
* echo 'Translation progress: ' . $progress . "%\n";
419387
* }
420388
* );
421-
* @endcode
389+
* </code></pre>
422390
*
423391
* @example Automatic language detection
424-
* @code
392+
* <pre><code class="language-php">
425393
* <?php
426394
* $engine = new LingoDotDevEngine(['apiKey' => $_ENV['LINGODOTDEV_API_KEY']]);
427395
* echo $engine->localizeText('Bonjour le monde', ['sourceLocale' => null, 'targetLocale' => 'en']);
428-
* @endcode
396+
* </code></pre>
429397
*
430398
* @throws \InvalidArgumentException When required params are missing or invalid
431399
* @throws \RuntimeException When API rejects or fails to process the request
@@ -449,23 +417,22 @@ public function localizeText(string $text, array $params, ?callable $progressCal
449417
* Localize a string into multiple languages and return texts in order.
450418
*
451419
* @param string $text Text content to translate into multiple languages
452-
* @param array<string, mixed> $params Batch translation options shared by all target locales:
420+
* @param array{sourceLocale:string,targetLocales:array<int,string>,fast?:bool} $params Batch translation options shared by all target locales:
453421
* - 'sourceLocale' (string, required): Language code of the original text (e.g., 'en')
454422
* - 'targetLocales' (string[], required): Array of language codes to translate into (e.g., ['es', 'fr', 'de'])
455423
* - 'fast' (bool): Trade translation quality for speed
456-
* @phpstan-param BatchLocalizeParams $params
457424
*
458425
* @return string[] Array of translated texts in same order as targetLocales parameter
459426
*
460427
* @example Batch translation to multiple languages
461-
* @code
428+
* <pre><code class="language-php">
462429
* <?php
463430
* $engine = new LingoDotDevEngine(['apiKey' => $_ENV['LINGODOTDEV_API_KEY']]);
464431
* $results = $engine->batchLocalizeText('Hello, world!', [
465432
* 'sourceLocale' => 'en',
466433
* 'targetLocales' => ['es', 'fr', 'de'],
467434
* ]);
468-
* @endcode
435+
* </code></pre>
469436
*
470437
* @throws \InvalidArgumentException When required params are missing or invalid
471438
* @throws \RuntimeException When an individual localization request fails
@@ -497,30 +464,28 @@ public function batchLocalizeText(string $text, array $params): array
497464
/**
498465
* Localize a chat transcript while preserving speaker names.
499466
*
500-
* @param array<int, array<string, string>> $chat Conversation history with speaker names and their messages. Each entry must include:
467+
* @param array<int, array{name:string,text:string}> $chat Conversation history with speaker names and their messages. Each entry must include:
501468
* - 'name' (string): Speaker label to preserve
502469
* - 'text' (string): Message content to translate
503-
* @phpstan-param ChatTranscript $chat
504-
* @param array<string, mixed> $params Chat translation options defining locale behavior and context:
470+
* @param array{targetLocale:string,sourceLocale?:string|null,fast?:bool,reference?:array<string, mixed>|null} $params Chat translation options defining locale behavior and context:
505471
* - 'targetLocale' (string, required): Language code to translate messages into (e.g., 'es', 'fr')
506472
* - 'sourceLocale' (string|null): Language code of original messages, null for auto-detection
507473
* - 'fast' (bool): Trade translation quality for speed
508474
* - 'reference' (array<string, mixed>|null): Context data or glossary terms to guide translation
509-
* @phpstan-param LocalizeParams $params
510-
* @param (callable(int): void)|null $progressCallback Called with completion percentage (0-100) during processing
475+
* @param callable|null $progressCallback Called with completion percentage (0-100) during processing
511476
*
512477
* @return array<int, array<string, string>> Translated messages keeping original speaker names unchanged
513478
*
514479
* @example Chat translation
515-
* @code
480+
* <pre><code class="language-php">
516481
* <?php
517482
* $engine = new LingoDotDevEngine(['apiKey' => $_ENV['LINGODOTDEV_API_KEY']]);
518483
* $conversation = [
519484
* ['name' => 'Alice', 'text' => 'Hello, how are you?'],
520485
* ['name' => 'Bob', 'text' => 'I am fine, thank you!']
521486
* ];
522487
* $engine->localizeChat($conversation, ['sourceLocale' => 'en', 'targetLocale' => 'de']);
523-
* @endcode
488+
* </code></pre>
524489
*
525490
* @throws \InvalidArgumentException When chat entries or params are invalid
526491
* @throws \RuntimeException When API rejects or fails to process the request
@@ -562,11 +527,11 @@ public function localizeChat(array $chat, array $params, ?callable $progressCall
562527
* @return string ISO language code detected by the API (e.g., 'en', 'es', 'zh')
563528
*
564529
* @example Language detection
565-
* @code
530+
* <pre><code class="language-php">
566531
* <?php
567532
* $engine = new LingoDotDevEngine(['apiKey' => $_ENV['LINGODOTDEV_API_KEY']]);
568533
* echo $engine->recognizeLocale('Bonjour le monde');
569-
* @endcode
534+
* </code></pre>
570535
*
571536
* @throws \InvalidArgumentException When input text is blank after trimming
572537
* @throws \RuntimeException When API response is invalid or request fails

0 commit comments

Comments
 (0)