Skip to content

Commit 8f7decc

Browse files
davidturnbulldavidturnbull
committed
docs: add examples
1 parent 6effbec commit 8f7decc

File tree

1 file changed

+276
-0
lines changed

1 file changed

+276
-0
lines changed

‎src/LingoDotDevEngine.php‎

Lines changed: 276 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -22,6 +22,51 @@
2222
* to detect the locale of free-form text. The engine handles request batching,
2323
* progress reporting, and surfacing validation or transport errors.
2424
*
25+
* @example Basic setup
26+
* ```php
27+
* <?php
28+
*
29+
* require 'vendor/autoload.php';
30+
*
31+
* use LingoDotDev\Sdk\LingoDotDevEngine;
32+
*
33+
* $engine = new LingoDotDevEngine([
34+
* 'apiKey' => $_ENV['LINGODOTDEV_API_KEY'],
35+
* ]);
36+
* ```
37+
*
38+
* @example Laravel integration
39+
* ```php
40+
* <?php
41+
*
42+
* namespace App\Http\Controllers;
43+
*
44+
* use Illuminate\Http\Request;
45+
* use LingoDotDev\Sdk\LingoDotDevEngine;
46+
*
47+
* class TranslationController extends Controller
48+
* {
49+
* private $engine;
50+
*
51+
* public function __construct()
52+
* {
53+
* $this->engine = new LingoDotDevEngine([
54+
* 'apiKey' => config('services.lingodotdev.api_key'),
55+
* ]);
56+
* }
57+
*
58+
* public function translateMessage(Request $request)
59+
* {
60+
* $translated = $this->engine->localizeText($request->message, [
61+
* 'sourceLocale' => $request->source_locale,
62+
* 'targetLocale' => $request->target_locale,
63+
* ]);
64+
*
65+
* return response()->json(['translated' => $translated]);
66+
* }
67+
* }
68+
* ```
69+
*
2570
* @category Localization
2671
* @package Lingodotdev\Sdk
2772
* @author Lingo.dev Team <hi@lingo.dev>
@@ -53,6 +98,28 @@ class LingoDotDevEngine
5398
* - 'batchSize' (int): Records per request, 1-250 (default: 25)
5499
* - 'idealBatchItemSize' (int): Max words per request, 1-2500 (default: 250)
55100
*
101+
* @example Configuration
102+
* ```php
103+
* <?php
104+
*
105+
* require 'vendor/autoload.php';
106+
*
107+
* use LingoDotDev\Sdk\LingoDotDevEngine;
108+
*
109+
* $engine = new LingoDotDevEngine([
110+
* 'apiKey' => $_ENV['LINGODOTDEV_API_KEY'],
111+
* 'batchSize' => 100,
112+
* 'idealBatchItemSize' => 1000,
113+
* ]);
114+
*
115+
* $result = $engine->localizeText('Configuration test', [
116+
* 'sourceLocale' => 'en',
117+
* 'targetLocale' => 'es',
118+
* ]);
119+
* echo $result;
120+
* // Output: Prueba de configuración
121+
* ```
122+
*
56123
* @throws \InvalidArgumentException When API key is missing or values fail validation
57124
*/
58125
public function __construct(array $config = [])
@@ -304,6 +371,35 @@ private function _createId(): string
304371
*
305372
* @return array<string, mixed> Translated data preserving original structure and non-text values
306373
*
374+
* @example Object translation
375+
* ```php
376+
* <?php
377+
*
378+
* require 'vendor/autoload.php';
379+
*
380+
* use LingoDotDev\Sdk\LingoDotDevEngine;
381+
*
382+
* $engine = new LingoDotDevEngine([
383+
* 'apiKey' => $_ENV['LINGODOTDEV_API_KEY'],
384+
* ]);
385+
*
386+
* $content = [
387+
* 'greeting' => 'Hello',
388+
* 'farewell' => 'Goodbye',
389+
* 'messages' => [
390+
* 'welcome' => 'Welcome to our service',
391+
* 'thanks' => 'Thank you for your business'
392+
* ]
393+
* ];
394+
*
395+
* $translated = $engine->localizeObject($content, [
396+
* 'sourceLocale' => 'en',
397+
* 'targetLocale' => 'fr',
398+
* ]);
399+
* print_r($translated);
400+
* // Output: Array with French translations maintaining structure
401+
* ```
402+
*
307403
* @throws \InvalidArgumentException When required params or reference data are invalid
308404
* @throws \RuntimeException When API rejects or fails to process the request
309405
*/
@@ -333,6 +429,117 @@ public function localizeObject(array $obj, array $params, ?callable $progressCal
333429
*
334430
* @return string Translated text, or empty string if translation unavailable
335431
*
432+
* @example Text translation
433+
* ```php
434+
* <?php
435+
*
436+
* require 'vendor/autoload.php';
437+
*
438+
* use LingoDotDev\Sdk\LingoDotDevEngine;
439+
*
440+
* $engine = new LingoDotDevEngine([
441+
* 'apiKey' => $_ENV['LINGODOTDEV_API_KEY'],
442+
* ]);
443+
*
444+
* $result = $engine->localizeText('Hello, world!', [
445+
* 'sourceLocale' => 'en',
446+
* 'targetLocale' => 'es',
447+
* ]);
448+
* echo $result;
449+
* // Output: ¡Hola, mundo!
450+
* ```
451+
*
452+
* @example Progress tracking
453+
* ```php
454+
* <?php
455+
*
456+
* require 'vendor/autoload.php';
457+
*
458+
* use LingoDotDev\Sdk\LingoDotDevEngine;
459+
*
460+
* $engine = new LingoDotDevEngine([
461+
* 'apiKey' => $_ENV['LINGODOTDEV_API_KEY'],
462+
* ]);
463+
*
464+
* $largeText = 'This is a very long text that needs translation...';
465+
*
466+
* $result = $engine->localizeText($largeText, [
467+
* 'sourceLocale' => 'en',
468+
* 'targetLocale' => 'es',
469+
* ], function ($progress) {
470+
* echo "Translation progress: $progress%\n";
471+
* });
472+
* // Output:
473+
* // Translation progress: 25%
474+
* // Translation progress: 50%
475+
* // Translation progress: 75%
476+
* // Translation progress: 100%
477+
* ```
478+
*
479+
* @example Translation parameters
480+
* ```php
481+
* <?php
482+
*
483+
* require 'vendor/autoload.php';
484+
*
485+
* use LingoDotDev\Sdk\LingoDotDevEngine;
486+
*
487+
* $engine = new LingoDotDevEngine([
488+
* 'apiKey' => $_ENV['LINGODOTDEV_API_KEY'],
489+
* ]);
490+
*
491+
* $result = $engine->localizeText('Hello world', [
492+
* 'sourceLocale' => 'en',
493+
* 'targetLocale' => 'es',
494+
* 'fast' => true,
495+
* ]);
496+
* echo $result;
497+
* // Output: Hola mundo
498+
* ```
499+
*
500+
* @example Automatic language detection
501+
* ```php
502+
* <?php
503+
*
504+
* require 'vendor/autoload.php';
505+
*
506+
* use LingoDotDev\Sdk\LingoDotDevEngine;
507+
*
508+
* $engine = new LingoDotDevEngine([
509+
* 'apiKey' => $_ENV['LINGODOTDEV_API_KEY'],
510+
* ]);
511+
*
512+
* $result = $engine->localizeText('Bonjour le monde', [
513+
* 'sourceLocale' => null,
514+
* 'targetLocale' => 'en',
515+
* ]);
516+
* echo $result;
517+
* // Output: Hello world
518+
* ```
519+
*
520+
* @example Error handling
521+
* ```php
522+
* <?php
523+
*
524+
* require 'vendor/autoload.php';
525+
*
526+
* use LingoDotDev\Sdk\LingoDotDevEngine;
527+
*
528+
* $engine = new LingoDotDevEngine([
529+
* 'apiKey' => $_ENV['LINGODOTDEV_API_KEY'],
530+
* ]);
531+
*
532+
* try {
533+
* $result = $engine->localizeText('Hello', [
534+
* 'sourceLocale' => 'en',
535+
* 'targetLocale' => 'es',
536+
* ]);
537+
* echo $result;
538+
* } catch (Exception $e) {
539+
* error_log('Translation failed: ' . $e->getMessage());
540+
* }
541+
* ```
542+
*
336543
* @throws \InvalidArgumentException When required params are missing or invalid
337544
* @throws \RuntimeException When API rejects or fails to process the request
338545
*/
@@ -362,6 +569,26 @@ public function localizeText(string $text, array $params, ?callable $progressCal
362569
*
363570
* @return string[] Array of translated texts in same order as targetLocales parameter
364571
*
572+
* @example Batch translation to multiple languages
573+
* ```php
574+
* <?php
575+
*
576+
* require 'vendor/autoload.php';
577+
*
578+
* use LingoDotDev\Sdk\LingoDotDevEngine;
579+
*
580+
* $engine = new LingoDotDevEngine([
581+
* 'apiKey' => $_ENV['LINGODOTDEV_API_KEY'],
582+
* ]);
583+
*
584+
* $results = $engine->batchLocalizeText('Hello, world!', [
585+
* 'sourceLocale' => 'en',
586+
* 'targetLocales' => ['es', 'fr', 'de'],
587+
* ]);
588+
* print_r($results);
589+
* // Output: ["¡Hola, mundo!", "Bonjour le monde!", "Hallo, Welt!"]
590+
* ```
591+
*
365592
* @throws \InvalidArgumentException When required params are missing or invalid
366593
* @throws \RuntimeException When an individual localization request fails
367594
*/
@@ -402,6 +629,38 @@ public function batchLocalizeText(string $text, array $params): array
402629
*
403630
* @return array<int, array{name: string, text: string}> Translated messages keeping original speaker names unchanged
404631
*
632+
* @example Chat translation
633+
* ```php
634+
* <?php
635+
*
636+
* require 'vendor/autoload.php';
637+
*
638+
* use LingoDotDev\Sdk\LingoDotDevEngine;
639+
*
640+
* $engine = new LingoDotDevEngine([
641+
* 'apiKey' => $_ENV['LINGODOTDEV_API_KEY'],
642+
* ]);
643+
*
644+
* $conversation = [
645+
* ['name' => 'Alice', 'text' => 'Hello, how are you?'],
646+
* ['name' => 'Bob', 'text' => 'I am fine, thank you!'],
647+
* ['name' => 'Alice', 'text' => 'What are you doing today?']
648+
* ];
649+
*
650+
* $translated = $engine->localizeChat($conversation, [
651+
* 'sourceLocale' => 'en',
652+
* 'targetLocale' => 'de',
653+
* ]);
654+
*
655+
* foreach ($translated as $message) {
656+
* echo $message['name'] . ': ' . $message['text'] . "\n";
657+
* }
658+
* // Output:
659+
* // Alice: Hallo, wie geht es dir?
660+
* // Bob: Mir geht es gut, danke!
661+
* // Alice: Was machst du heute?
662+
* ```
663+
*
405664
* @throws \InvalidArgumentException When chat entries or params are invalid
406665
* @throws \RuntimeException When API rejects or fails to process the request
407666
*/
@@ -441,6 +700,23 @@ public function localizeChat(array $chat, array $params, ?callable $progressCall
441700
*
442701
* @return string ISO language code detected by the API (e.g., 'en', 'es', 'zh')
443702
*
703+
* @example Language detection
704+
* ```php
705+
* <?php
706+
*
707+
* require 'vendor/autoload.php';
708+
*
709+
* use LingoDotDev\Sdk\LingoDotDevEngine;
710+
*
711+
* $engine = new LingoDotDevEngine([
712+
* 'apiKey' => $_ENV['LINGODOTDEV_API_KEY'],
713+
* ]);
714+
*
715+
* $locale = $engine->recognizeLocale('Bonjour le monde');
716+
* echo $locale;
717+
* // Output: fr
718+
* ```
719+
*
444720
* @throws \InvalidArgumentException When input text is blank after trimming
445721
* @throws \RuntimeException When API response is invalid or request fails
446722
*/

0 commit comments

Comments
 (0)