Looking to hire Laravel developers? Try LaraJobs

translations-laravel maintained by mybeast

Author
Last update
2026/11/18 15:51 (v0.1.0)
License
Downloads
0

Comments
comments powered by Disqus

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. What lang/ 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 key lang/ 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=600 waits 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 it pt-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.