translations-laravel maintained by mybeast
mybeast/translations-laravel
The Laravel SDK for My Beast Translations: your app's lang/ files go
to the service as they are, people review the words there, and the reviewed words come back into lang/.
PHP ≥ 8.2, Laravel 12 and 13.
Plug it in
composer require mybeast/translations-laravel
MYBEAST_TRANSLATIONS_URL=https://services.my-beast.com/translations
MYBEAST_TRANSLATIONS_SECRET=sk_….…
Where the values come from. id makes the server secret with the project, and Secrets keeps the URL and secret lines, filled in, in each of the project's environments. A secret made by hand is on the project's Settings → Keys, shown once, when made.
That is all. The source language is the app's fallback locale (config/app.php); set MYBEAST_TRANSLATIONS_SOURCE
when it is another.
Use
php artisan translations:push # sends lang/ in every locale; new keys are added and translated
php artisan translations:push --prune # the main branch's push: keys lang/ no longer has are archived
php artisan translations:pull # writes lang/ in the other languages: the words that are served
php artisan translations:check # changes nothing; ends 1 when a language misses keys or a text fails a check
php artisan translations:status # how the app's strings stand
- push sends each group (
lang/{locale}/*.php, folders too) and the JSON file (lang/{locale}.json). The PHP files are read by your app's own loader and sent as their lines: no code leaves the app. Whatlang/has in another language comes in as the machine's words and goes through the checks; it never goes over words a person reviewed - there it waits beside them as a proposal. A first push may say the other languages are reviewed already:--existing=reviewed. A keylang/no longer has is archived only with--prune, so a feature branch's push never removes one. What is missing in a language is translated by the machine: a few at once, many in the background.--wait=600waits for it. - pull writes every file in each of the project's other languages. A group is written as a PHP file - short arrays, four spaces, the keys in the source's order -, the JSON file as the source's is written. They hold the reviewed words, and the machine's where the language uses them at once; a key with nothing to serve is left out, so Laravel falls back to the source language there. The source language's files are never touched, and a file the service has no words for yet is left as it is: no empty file is made, and words that are here are never replaced by none. Each file is written as it comes: a pull that fails partway keeps the files it wrote, and the others stay as the repo has them.
- check is for CI. Words a person approved as they are pass, so a difference that is on purpose is accepted once.
- A locale
lang/spells its own way (pt_BR) keeps its folder; the service calls itpt-BR. - Packages' own words (
lang/vendor) are left alone.
The commands end with 0, 1 (a check found something), 2 (nothing to do here: no files, or a push's --existing
that is neither machine nor reviewed) or 3 (the service did not take it), and say why in words.
Settings
php artisan vendor:publish --tag=mybeast-translations-config writes config/mybeast-translations.php:
| Setting | What |
|---|---|
url, secret |
The product's address and the project's server secret |
source |
The language your developers write; left empty, the app's fallback locale |
groups, json |
Whether the groups and the JSON file are your app's own words (both, by default) |
except |
Groups to leave out, by their file: ['validation', 'admin/users'] |
timeout |
One call's wait at most, in seconds (300) |
For JSON files outside lang/ (a front end's i18next files), use the mybeast-translations command of the
My Beast CLI.
Tests
composer test # the commands in a tiny Laravel app, against a stand-in of the service's API
vendor/bin/pint --test
Releasing
Add the version to CHANGELOG.md, then tag it: git tag v0.2.0 && git push --tags. Packagist reads the tag through
its GitHub hook; there is no version in composer.json. The Tests workflow runs on the tag as on every push: Laravel 12
on PHP 8.2 to 8.4, Laravel 13 on 8.3 and 8.4.
Licence
MIT.