Laravel Tolgee Laravel Package

Getting Started

dusanbre/laravel-tolgee wraps the Tolgee translation platform so you can keep translations in Tolgee as the source of truth while still using standard Laravel __() / trans() helpers in your app. The v1.1.0 release is a modest one — a refactor of TolgeeService for improved path handling and formatting, plus a CI dependency bump — but the core workflow is unchanged, so the same starting steps apply.

Minimal setup:

1. Require the package: composer require dusanbre/laravel-tolgee (or update with composer update dusanbre/laravel-tolgee to pick up v1.1.0).
2. Publish the config so you can see what paths and locales are wired up: php artisan vendor:publish --provider="Dusanbre\\LaravelTolgee\\LaravelTolgeeServiceProvider" (check vendor/ for the exact tag if this one doesn't resolve).
3. Add your Tolgee credentials to .env (typically TOLGEE_API_KEY, TOLGEE_PROJECT_ID, and optionally TOLGEE_BASE_URL for self-hosted instances). Confirm the variable names in config/tolgee.php — they are the contract, not the names in this paragraph.
4. Run php artisan list and look for the package's sync commands. That is the fastest way to discover the actual command names the package registers.

Your first real use case: pull Tolgee translations into lang/ before a request needs them. Configure the locale → path mapping in config/tolgee.php (e.g. en → lang/en.json, de → lang/de), run the pull/sync command, then verify a key resolves with php artisan tinker → __('some.key'). Only after that works should you wire push (local → Tolgee) into anything.

Look first at config/tolgee.php and TolgeeService itself. Given v1.1.0 changed path handling, reading the service's path-building and formatting logic is the best 15 minutes you can spend.

Implementation Patterns

Pull-on-deploy. The most common day-to-day pattern is: build stage pulls translations from Tolgee, then the compiled artifacts ship. Run the sync command in CI/CD rather than at request time so your app never blocks on a Tolgee API call during a user request.

Push-on-merge (optional). If developers add keys locally, a push command can sync new keys up on merge to main. Keep this separate from the pull path — a single bidirectional "sync" command is harder to reason about when a build fails.

Service injection for programmatic access. Where you need runtime access (e.g. a translation-management admin screen, or a custom import job), resolve TolgeeService from the container and call its methods directly. Because v1.1.0 refactored it, treat the public method signatures as the stable surface and avoid reaching into protected helpers.

Formatting conventions. The v1.1.0 "formatting" refactor is the part most likely to bite you. If your Tolgee keys are nested (auth.login.title) and your files are flat JSON, verify the key casing and delimiter behaviour matches what Laravel's trans() expects. A common integration pattern is to normalise keys in one place and assert the shape in a feature test:

it('resolves a tolgee-synced key', function () {
    expect(__('auth.login.title'))->not->toBe('auth.login.title');
});

CI integration. Add the pull command as a composer or deploy script step, and fail the build if the command exits non-zero. That way a bad API key or a malformed locale path surfaces in CI, not in production on first request.

Local development. Developers should be able to run the pull command locally once and commit nothing — keep lang/ synced files out of version control if Tolgee is the source of truth, or in version control if you need offline builds. Pick one; mixing both is where drift starts.

Gotchas and Tips

Re-run path-sensitive tests after upgrading to v1.1.0. The TolgeeService refactor touched path handling and formatting. Any custom code that constructed file paths, assumed a trailing slash, or relied on the previous key formatting needs review. Run your translation tests and diff the generated lang/ output against the previous release before shipping.

Clear caches after any sync. php artisan config:clear if you changed config, and be aware that php artisan config:cache in production freezes config values — including any paths — at build time. If your deploy pulls translations after config caching, the service may read stale paths.

Watch the locale-code mismatch. Tolgee locales and Laravel locale directories don't always agree (en-US vs en, pt_BR vs pt-BR). If a locale silently produces an empty file, check the mapping in config/tolgee.php first.

API failures are easy to misread as "missing translation." A 401 from a bad key looks identical to a key that simply doesn't exist, because both leave you with the raw key string in the view. Log the service's HTTP responses during setup, and only turn down logging once you trust the pipeline.

Don't run sync commands on every request. It's tempting in early development; it will rate-limit you and add latency. Cache the pulled files on disk and refresh them on deploy or on a schedule.

Extension points. If you need custom behaviour (e.g. post-processing keys, custom HTTP client options), prefer decorating/wrapping TolgeeService in your own class over editing vendor code — the v1.1.0 refactor is a good reminder that the service internals are moving. Bind your wrapper in a service provider and inject that instead.

The dependabot bump is maintainer-only. Upgrading stefanzweifel/git-auto-commit-action from 5 to 6 affects the package's own release workflow, not your application. No action needed on your side beyond noting CI changes if you fork the repo.

Version pinning. Because v1.1.0 is a minor release with an internal refactor, pin to ^1.1 and rely on your translation test suite as the regression guard for future patches.