Skip to content

Commit df140d0

Browse files
Aldr0nAldr0n
committed
docs(LGT-167): Update README
1 parent 27df782 commit df140d0

File tree

1 file changed

+212
-32
lines changed

1 file changed

+212
-32
lines changed

‎README.md‎

Lines changed: 212 additions & 32 deletions
Original file line numberDiff line numberDiff line change
@@ -1,11 +1,11 @@
1-
# Linguist Connector for Laravel
1+
# Linguist Connector for Laravel
22

33
[![Latest Version on Packagist](https://img.shields.io/packagist/v/hyperlinkgroup/linguist.svg?style=flat-square)](https://packagist.org/packages/hyperlinkgroup/linguist)
44
[![GitHub Tests Action Status](https://img.shields.io/github/actions/workflow/status/hyperlinkgroup/linguist-package/run-tests.yml?branch=main&label=tests&style=flat-square)](https://github.com/hyperlinkgroup/linguist/actions?query=workflow%3Arun-tests+branch%3Amain)
55
[![GitHub Code Style Action Status](https://img.shields.io/github/actions/workflow/status/hyperlinkgroup/linguist-package/fix-php-code-style-issues.yml?branch=main&label=code%20style&style=flat-square)](https://github.com/hyperlinkgroup/linguist/actions?query=workflow%3A"Fix+PHP+code+style+issues"+branch%3Amain)
66
[![Total Downloads](https://img.shields.io/packagist/dt/hyperlink/linguist.svg?style=flat-square)](https://packagist.org/packages/hyperlink/linguist)
77

8-
A package to help you download your language files from [Linguist](https://app.linguist.eu) — A better way to manage you language files.
8+
A package to help you manage your translation files with [Linguist](https://app.linguist.eu) — A better way to manage your language files.
99

1010
<img src="./art/header.jpg" alt="linguist-package-header">
1111

@@ -23,44 +23,200 @@ You can publish the config file with:
2323
php artisan vendor:publish --tag="linguist-config"
2424
```
2525

26-
This is the contents of the published config file:
26+
## Quick Start (Setup Wizard)
27+
28+
The easiest way to get started is using the interactive setup wizard:
29+
30+
```bash
31+
php artisan linguist:setup
32+
```
33+
34+
This wizard will guide you through:
35+
36+
1. **API Token** - Enter your Linguist API token
37+
2. **Project Selection** - Choose an existing project or create a new one
38+
3. **Sync Mode** - Select how you want to synchronize translations:
39+
- **Sync**: Merge local and remote translations (two-way)
40+
- **Pull**: Download from Linguist (overwrite local)
41+
- **Push**: Upload local translations to Linguist
42+
4. **Options** - Configure setup preferences and optional auto-translation
43+
44+
### Interactive Only
45+
46+
`linguist:setup` now runs as an interactive wizard and prompts for all setup values during execution.
47+
48+
## Configuration
49+
50+
The published config file (`config/linguist.php`):
2751

2852
```php
2953
return [
30-
/*
31-
|--------------------------------------------------------------------------
32-
| Linguist API URL
33-
|--------------------------------------------------------------------------
34-
*/
35-
'url' => env('LINGUIST_URL', 'https://api.linguist.eu/'),
36-
37-
/*
38-
|--------------------------------------------------------------------------
39-
| Linguist Project Slug
40-
|--------------------------------------------------------------------------
41-
*/
42-
'project' => env('LINGUIST_PROJECT', ''),
43-
44-
/*
45-
|--------------------------------------------------------------------------
46-
| Linguist API Token
47-
|--------------------------------------------------------------------------
48-
*/
49-
'token' => env('LINGUIST_TOKEN', ''),
50-
51-
/*
52-
|--------------------------------------------------------------------------
53-
| Temporary Directory for Translations while processing
54-
|--------------------------------------------------------------------------
55-
*/
56-
'temporary_directory' => 'tmp/translations',
54+
/*
55+
|--------------------------------------------------------------------------
56+
| Linguist API URL
57+
|--------------------------------------------------------------------------
58+
*/
59+
'url' => env('LINGUIST_URL', 'https://api.linguist.eu/'),
60+
61+
/*
62+
|--------------------------------------------------------------------------
63+
| Linguist Project Slug
64+
|--------------------------------------------------------------------------
65+
*/
66+
'project' => env('LINGUIST_PROJECT', ''),
67+
68+
/*
69+
|--------------------------------------------------------------------------
70+
| Linguist API Token
71+
|--------------------------------------------------------------------------
72+
*/
73+
'token' => env('LINGUIST_TOKEN', ''),
74+
75+
/*
76+
|--------------------------------------------------------------------------
77+
| Temporary Directory for Translations while processing
78+
|--------------------------------------------------------------------------
79+
*/
80+
'temporary_directory' => 'tmp/translations',
5781
];
5882
```
5983

60-
## Usage
84+
The setup wizard automatically writes these values to your `.env` file.
85+
86+
## Commands
87+
88+
### `linguist:setup`
89+
90+
Interactive wizard for initial setup and configuration. Handles project creation/selection, sync mode configuration, and API token management.
91+
92+
### `linguist:sync`
93+
94+
Runs translation synchronization in one of three modes (`sync`, `pull`, `push`).
95+
96+
```bash
97+
php artisan linguist:sync
98+
```
99+
100+
If run interactively, the command prompts for mode selection (same choices as setup).
101+
For scheduler/non-interactive execution, the command defaults to `sync` mode unless you pass an explicit mode flag:
102+
103+
```bash
104+
php artisan linguist:sync --mode=sync
105+
php artisan linguist:sync --pull
106+
php artisan linguist:sync --push
107+
```
108+
109+
Mode-specific options:
110+
111+
```bash
112+
# sync mode options
113+
php artisan linguist:sync --sync --prune-remote-keys
114+
php artisan linguist:sync --sync --no-activate-missing-languages
115+
116+
# push mode options
117+
php artisan linguist:sync --push --overwrite
118+
php artisan linguist:sync --push --languages=EN,DE
119+
```
120+
121+
`--prune-remote-keys`, `--no-activate-missing-languages`, and `--overwrite` are currently accepted flags but are not yet applied by the sync/push action internals.
122+
123+
## Sync Modes
124+
125+
### Sync Mode (Recommended)
126+
127+
Performs a two-way merge between local and remote translations:
128+
129+
- Downloads remote translations
130+
- Merges with local translations (remote values take precedence for conflicts)
131+
132+
### Pull Mode
133+
134+
Downloads all translations from Linguist and overwrites local files:
135+
136+
- Fetches all active languages
137+
- Downloads translation files
138+
- Replaces local files entirely
139+
140+
### Push Mode
141+
142+
Uploads local translations to Linguist:
143+
144+
- Reads all local translation files
145+
- Creates/updates keys on remote
146+
- Preserves remote-only keys
147+
148+
## Advanced Usage
149+
150+
### Using Actions Directly
151+
152+
For custom implementations, you can call the provided actions directly:
61153

62154
```php
63-
\Hyperlinkgroup\Linguist\Linguist::handle();
155+
use Hyperlinkgroup\Linguist\Services\LinguistApiClient;
156+
use Hyperlinkgroup\Linguist\Actions\SyncTranslations;
157+
158+
// API Client
159+
$client = app(LinguistApiClient::class);
160+
$projects = $client->listProjects()->json('data');
161+
162+
// Sync Action
163+
$result = SyncTranslations::run(
164+
projectSlug: 'my-project',
165+
pruneRemoteKeys: true,
166+
);
167+
168+
echo $result->getSummaryMessage();
169+
```
170+
171+
### Data Transfer Objects
172+
173+
The package provides typed DTOs for configuration:
174+
175+
```php
176+
use Hyperlinkgroup\Linguist\DTO\SetupInput;
177+
use Hyperlinkgroup\Linguist\DTO\SyncResult;
178+
179+
$input = new SetupInput(
180+
apiToken: 'your-token',
181+
projectSlug: 'my-project',
182+
syncMode: 'sync',
183+
pruneRemoteKeys: false,
184+
activateMissingLanguages: true,
185+
);
186+
187+
// From array
188+
$input = SetupInput::fromArray([
189+
'api_token' => 'your-token',
190+
'project_slug' => 'my-project',
191+
]);
192+
193+
// Sync results
194+
$result = SyncTranslations::run(projectSlug: 'my-project');
195+
$result->overallSuccess; // bool
196+
$result->hasPartialSuccess(); // bool
197+
$result->getFailedLanguages(); // array
198+
$result->getSummaryMessage(); // string
199+
```
200+
201+
## Error Handling and Reporting
202+
203+
All sync operations return detailed `SyncResult` objects with:
204+
205+
- **Per-language results**: Success/failure status for each language
206+
- **Partial success detection**: Identify which languages succeeded or failed
207+
- **Detailed error messages**: Specific failure reasons per language
208+
- **Key counts**: Total processed and failed key counts
209+
210+
Example output:
211+
212+
```
213+
Sync Results:
214+
Partial sync completed. 2 languages successful, 1 languages failed. (150 keys processed, 3 failed)
215+
216+
Per-language results:
217+
✓ EN
218+
✓ DE
219+
✗ FR: Failed to download translations
64220
```
65221

66222
## Testing
@@ -69,6 +225,30 @@ return [
69225
composer test
70226
```
71227

228+
The test suite includes:
229+
230+
- Unit tests for actions and core orchestration logic
231+
- DTO validation tests
232+
- Legacy integration tests
233+
- HTTP mocking for API interactions
234+
235+
## API Endpoints
236+
237+
The package communicates with Linguist's REST API:
238+
239+
- `GET /projects` - List available projects
240+
- `POST /projects` - Create new project
241+
- `PATCH /projects/{project}` - Update project
242+
- `GET /projects/{project}/languages` - List project languages
243+
- `GET /projects/{project}/export/json/{language}` - Get export URL
244+
- `GET /projects/{project}/translation-keys` - List translation keys
245+
- `POST /projects/{project}/translation-keys` - Create/update key
246+
- `PATCH /projects/{project}/translation-keys/{key}` - Update key
247+
- `DELETE /projects/{project}/translation-keys/{key}` - Delete key
248+
- `POST /projects/{project}/translate` - Trigger auto-translation
249+
250+
All endpoints require Bearer token authentication.
251+
72252
## License
73253

74254
The MIT License (MIT). Please see [License File](LICENSE.md) for more information.

0 commit comments

Comments
 (0)