Skip to content

Commit 4ab9e07

Browse files
github-actions[bot]github-actions[bot]
committed
docs: update markdown API reference [skip ci]
1 parent e2cbd6d commit 4ab9e07

File tree

2 files changed

+317
-0
lines changed

2 files changed

+317
-0
lines changed

‎docs/Home.md‎

Lines changed: 12 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,12 @@
1+
2+
This is an automatically generated documentation for **Documentation**.
3+
4+
## Namespaces
5+
6+
### \LingoDotDev\Sdk
7+
8+
#### Classes
9+
10+
| Class | Description |
11+
|--------------------------------------------------------------------|---------------------------------------------------------------------------|
12+
| [`LingoDotDevEngine`](./classes/LingoDotDev/Sdk/LingoDotDevEngine) | LingoDotDevEngine wraps the Lingo.dev localization API for PHP consumers. |

‎docs/classes/LingoDotDev/Sdk/LingoDotDevEngine.md‎

Lines changed: 305 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,305 @@
1+
2+
LingoDotDevEngine wraps the Lingo.dev localization API for PHP consumers.
3+
4+
Use a single engine instance to translate strings, arrays, and chat logs, or
5+
to detect the locale of free-form text. The engine handles request batching,
6+
progress reporting, and surfacing validation or transport errors.
7+
8+
***
9+
10+
* Full name: `\LingoDotDev\Sdk\LingoDotDevEngine`
11+
12+
**See Also:**
13+
14+
* https://lingo.dev
15+
16+
## Properties
17+
18+
### config
19+
20+
Configuration options for the Engine.
21+
22+
```php
23+
protected array<string,mixed> $config
24+
```
25+
26+
***
27+
28+
### _httpClient
29+
30+
HTTP client for API requests.
31+
32+
```php
33+
private \GuzzleHttp\Client $_httpClient
34+
```
35+
36+
***
37+
38+
## Methods
39+
40+
### __construct
41+
42+
Build an engine with your API key and optional batching limits.
43+
44+
```php
45+
public __construct(array<string,mixed> $config = []): mixed
46+
```
47+
48+
**Parameters:**
49+
50+
| Parameter | Type | Description |
51+
|-----------|-------------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
52+
| `$config` | **array<string,mixed>** | Configuration options:
53+
- 'apiKey' (string, required): Your API token
54+
- 'apiUrl' (string): API base URL (default: https://engine.lingo.dev)
55+
- 'batchSize' (int): Records per request, 1-250 (default: 25)
56+
- 'idealBatchItemSize' (int): Max words per request, 1-2500 (default: 250) |
57+
58+
**Throws:**
59+
60+
When API key is missing or values fail validation
61+
- [`InvalidArgumentException`](../../InvalidArgumentException)
62+
63+
***
64+
65+
### _localizeChunk
66+
67+
Localize a single chunk of content.
68+
69+
```php
70+
private _localizeChunk(string|null $sourceLocale, string $targetLocale, array<string,mixed> $payload, string $workflowId, bool $fast): array<string,mixed>
71+
```
72+
73+
**Parameters:**
74+
75+
| Parameter | Type | Description |
76+
|-----------------|-------------------------|--------------------------------------------------------------------------------|
77+
| `$sourceLocale` | **string\|null** | Language code of the original text (e.g., 'en', 'es'), null for auto-detection |
78+
| `$targetLocale` | **string** | Language code to translate into (e.g., 'fr', 'de') |
79+
| `$payload` | **array<string,mixed>** | Content chunk with optional reference data for context |
80+
| `$workflowId` | **string** | Unique identifier for tracking related translation requests |
81+
| `$fast` | **bool** | Enable faster translation at potential quality tradeoff |
82+
83+
**Return Value:**
84+
85+
Translated chunk maintaining original structure
86+
87+
**Throws:**
88+
89+
When reference is not an array
90+
- [`InvalidArgumentException`](../../InvalidArgumentException)
91+
When API request fails
92+
- [`RuntimeException`](../../RuntimeException)
93+
94+
***
95+
96+
### _extractPayloadChunks
97+
98+
Extract payload chunks based on the ideal chunk size.
99+
100+
```php
101+
private _extractPayloadChunks(array<string,mixed> $payload): array<int,array<string,mixed>>
102+
```
103+
104+
**Parameters:**
105+
106+
| Parameter | Type | Description |
107+
|------------|-------------------------|---------------------------|
108+
| `$payload` | **array<string,mixed>** | The payload to be chunked |
109+
110+
**Return Value:**
111+
112+
Array of payload chunks
113+
114+
***
115+
116+
### _countWordsInRecord
117+
118+
Count words in a record or array.
119+
120+
```php
121+
private _countWordsInRecord(mixed $payload): int
122+
```
123+
124+
**Parameters:**
125+
126+
| Parameter | Type | Description |
127+
|------------|-----------|-------------------------------|
128+
| `$payload` | **mixed** | The payload to count words in |
129+
130+
**Return Value:**
131+
132+
Total number of words
133+
134+
***
135+
136+
### _createId
137+
138+
Generate a unique ID.
139+
140+
```php
141+
private _createId(): string
142+
```
143+
144+
**Return Value:**
145+
146+
Unique ID
147+
148+
***
149+
150+
### localizeObject
151+
152+
Localize every string in a nested array while keeping its shape intact.
153+
154+
```php
155+
public localizeObject(array<string,mixed> $obj, array<string,mixed> $params, null|callable $progressCallback = null): array<string,mixed>
156+
```
157+
158+
**Parameters:**
159+
160+
| Parameter | Type | Description |
161+
|---------------------|-------------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
162+
| `$obj` | **array<string,mixed>** | Nested data structure containing text to translate |
163+
| `$params` | **array<string,mixed>** | Parameters:
164+
- 'targetLocale' (string, required): Language code to translate into (e.g., 'es', 'fr')
165+
- 'sourceLocale' (string\|null): Language code of original text, null for auto-detection
166+
- 'fast' (bool): Trade translation quality for speed
167+
- 'reference' (array): Context or glossary terms to guide translation |
168+
| `$progressCallback` | **null\|callable** | Invoked per batch with (percentage complete, current batch, translated batch) |
169+
170+
**Return Value:**
171+
172+
Translated data preserving original structure and non-text values
173+
174+
**Throws:**
175+
176+
When required params or reference data are invalid
177+
- [`InvalidArgumentException`](../../InvalidArgumentException)
178+
When API rejects or fails to process the request
179+
- [`RuntimeException`](../../RuntimeException)
180+
181+
***
182+
183+
### localizeText
184+
185+
Localize a single string and return the translated text.
186+
187+
```php
188+
public localizeText(string $text, array<string,mixed> $params, null|callable $progressCallback = null): string
189+
```
190+
191+
**Parameters:**
192+
193+
| Parameter | Type | Description |
194+
|---------------------|-------------------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
195+
| `$text` | **string** | Text content to translate |
196+
| `$params` | **array<string,mixed>** | Parameters:
197+
- 'targetLocale' (string, required): Language code to translate into (e.g., 'es', 'fr')
198+
- 'sourceLocale' (string\|null): Language code of original text, null for auto-detection
199+
- 'fast' (bool): Prioritize speed over translation quality
200+
- 'reference' (array): Context, terminology, or style guidelines for translation |
201+
| `$progressCallback` | **null\|callable** | Called with completion percentage (0-100) during processing |
202+
203+
**Return Value:**
204+
205+
Translated text, or empty string if translation unavailable
206+
207+
**Throws:**
208+
209+
When required params are missing or invalid
210+
- [`InvalidArgumentException`](../../InvalidArgumentException)
211+
When API rejects or fails to process the request
212+
- [`RuntimeException`](../../RuntimeException)
213+
214+
***
215+
216+
### batchLocalizeText
217+
218+
Localize a string into multiple languages and return texts in order.
219+
220+
```php
221+
public batchLocalizeText(string $text, array<string,mixed> $params): string[]
222+
```
223+
224+
**Parameters:**
225+
226+
| Parameter | Type | Description |
227+
|-----------|-------------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
228+
| `$text` | **string** | Text content to translate into multiple languages |
229+
| `$params` | **array<string,mixed>** | Parameters:
230+
- 'sourceLocale' (string, required): Language code of the original text (e.g., 'en')
231+
- 'targetLocales' (string[], required): Array of language codes to translate into (e.g., ['es', 'fr', 'de'])
232+
- 'fast' (bool): Apply speed optimization to all translations |
233+
234+
**Return Value:**
235+
236+
Array of translated texts in same order as targetLocales parameter
237+
238+
**Throws:**
239+
240+
When required params are missing or invalid
241+
- [`InvalidArgumentException`](../../InvalidArgumentException)
242+
When an individual localization request fails
243+
- [`RuntimeException`](../../RuntimeException)
244+
245+
***
246+
247+
### localizeChat
248+
249+
Localize a chat transcript while preserving speaker names.
250+
251+
```php
252+
public localizeChat(array<int,array{name: string, text: string}> $chat, array<string,mixed> $params, null|callable $progressCallback = null): array<int,array{name: string, text: string}>
253+
```
254+
255+
**Parameters:**
256+
257+
| Parameter | Type | Description |
258+
|---------------------|--------------------------------------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
259+
| `$chat` | **array<int,array{name: string, text: string}>** | Conversation history with speaker names and their messages |
260+
| `$params` | **array<string,mixed>** | Parameters:
261+
- 'targetLocale' (string, required): Language code to translate messages into (e.g., 'es', 'fr')
262+
- 'sourceLocale' (string\|null): Language of original messages, null for auto-detection
263+
- 'fast' (bool): Optimize for speed over translation quality
264+
- 'reference' (array): Conversation context or domain-specific terminology |
265+
| `$progressCallback` | **null\|callable** | Called with completion percentage (0-100) during processing |
266+
267+
**Return Value:**
268+
269+
Translated messages keeping original speaker names unchanged
270+
271+
**Throws:**
272+
273+
When chat entries or params are invalid
274+
- [`InvalidArgumentException`](../../InvalidArgumentException)
275+
When API rejects or fails to process the request
276+
- [`RuntimeException`](../../RuntimeException)
277+
278+
***
279+
280+
### recognizeLocale
281+
282+
Identify the locale of the provided text.
283+
284+
```php
285+
public recognizeLocale(string $text): string
286+
```
287+
288+
**Parameters:**
289+
290+
| Parameter | Type | Description |
291+
|-----------|------------|--------------------------------------------------------------------|
292+
| `$text` | **string** | Sample text for language detection (longer text improves accuracy) |
293+
294+
**Return Value:**
295+
296+
ISO language code detected by the API (e.g., 'en', 'es', 'zh')
297+
298+
**Throws:**
299+
300+
When input text is blank after trimming
301+
- [`InvalidArgumentException`](../../InvalidArgumentException)
302+
When API response is invalid or request fails
303+
- [`RuntimeException`](../../RuntimeException)
304+
305+
***

0 commit comments

Comments
 (0)