Laravel Translations Laravel Package

Getting Started

This package is designed to move Laravel translations out of flat lang/*.php files and into a manageable store (typically a database table) so they can be edited, imported, and exported without redeploying. Because it has very low adoption (3 stars, 0 dependents), treat the README and src/ as the source of truth and pin the exact version in composer.json.

Minimal setup

composer require backstage/laravel-translations
php artisan vendor:publish --tag="laravel-translations-config"
php artisan vendor:publish --tag="laravel-translations-migrations"
php artisan migrate

Then open the published config (config/laravel-translations.php) and check three things before doing anything else:

1. Route prefix and middleware — this is a backstage/admin tool, so confirm it is behind auth and any admin middleware, not publicly exposed.
2. Driver / storage — whether translations are read from DB, files, or both, and in what precedence.
3. Cache toggle — whether reads hit the DB per request or a cache store.

Where to look first

• config/laravel-translations.php — route prefix, table names, cache, loader binding.
• The service provider — what it binds into Laravel's translator (this tells you whether __() and @lang now resolve from the DB).
• The Translation model and migrations — the schema you'll query and seed.
• Console commands (php artisan list | grep -i translation) — import/export/sync commands are the highest-leverage entry point.

First use case

The fastest win is a read-only roll-out: import your existing lang/ files into the package's storage, confirm the UI shows them, and leave the loader on the default file-based behavior. Once you trust the import, switch the loader to DB-backed and let translators edit in the admin UI. This gives you a safety net if anything looks wrong.

# Example — verify exact command names in the README
php artisan translations:import
php artisan translations:export

Implementation Patterns

1. DB-backed loader with a file fallback

The typical pattern is that the package swaps Laravel's translation.loader binding for a database-backed loader. In practice, views keep using __('messages.welcome') unchanged — this is the main reason to adopt it, since it means zero refactoring of Blade templates. Keep a file-based fallback for keys that haven't been imported yet so missing UI strings degrade to the original value instead of the raw key.

2. Import → edit → export workflow

Treat the DB as the working copy, not the canonical source, unless you have strong reasons otherwise:

lang/*.php  --import-->  DB  --edit in UI-->  DB  --export-->  lang/*.php (or deploy artifacts)

In CI you can run translations:export and diff the generated files against what's committed. That gives you reviewable PRs for translation changes and keeps translations in version control — a big win with non-technical translators.

3. Seeding baseline translations

Use the package's model or import in a seeder so new environments (and tests) start with a populated translation table:

// database/seeders/TranslationSeeder.php
public function run(): void
{
    $this->call(\Backstage\Translations\Console\ImportCommand::class);
    // or iterate Translation::upsert([...]) for a curated baseline
}

Pair this with RefreshDatabase in feature tests so translation-dependent assertions don't depend on manual setup.

4. Grouping and key conventions

Adopt a strict key convention early (group.key, never full sentences as keys) because the admin UI is only as usable as your naming. Group by domain (auth, validation, emails, admin_users) rather than by page. When you have multiple frontends or namespaces, use Laravel's namespace::group.key form so the package's filtering stays meaningful.

5. Cache-aware reads

If the package exposes a cache, enable it in production for reads and bust it on writes. The common implementation uses a cache key per locale (or per locale+group). Wire the package's write path into your deployment/cache-clear routine:

// In a deploy script or a model observer
Cache::forget("translations.{$locale}");

If the package doesn't bust its own cache, add a model observer on Translation saved/deleted that calls translator->setLoaded([]) or flushes the relevant cache keys.

6. Integration tip: middleware-gated UI

If you want the editor in a staging admin panel but not production, gate it in config/laravel-translations.php:

'routes' => [
    'enabled' => env('TRANSLATIONS_UI_ENABLED', false),
    'middleware' => ['web', 'auth', 'can:manage-translations'],
    'prefix' => 'backstage/translations',
],

Pair this with a Gate/Policy (manage-translations) so authorization is centralized and auditable.

7. CLI-first for teams

For teams that don't want a UI in production, use the package's console commands as the primary interface: export on deploy, import in a nightly job, and use the UI only locally or on staging. This pattern keeps the DB writes out of production and sidesteps most cache-invalidation hazards.

Gotchas and Tips

Cache invalidation is the #1 issue. Laravel's translator and view-level caching will happily serve stale strings after an edit. Decide up front whether the package invalidates on write — if not, wire it yourself (an observer or an event listener on the package's write events). In dev, always test with CACHE_STORE=array and with a real cache store, since behavior differs.

Precedence between files and DB. Most packages default to DB-first and fall back to files, but confirm which side wins for duplicate keys. If you export to files and later import, a round-trip can reorder or reformat lang/*.php files; use translations:export --dry-run (if offered) or diff carefully. Do not keep editing the same key in both places.

Migration publishing conflicts. Publishing migrations that collide with existing tables or use a fixed timestamp is common in small packages. If the migration has a hardcoded date, rename it before publishing or review the file manually instead of --force. If you already have a translations table (e.g., from spatie/laravel-translation-loader) this package may not share it cleanly — check column names before migrating.

Routes are not auth-guarded by default in many such packages. Never trust the default middleware. Confirm in the config, and add a policy. An open translation editor is a content-injection vector.

Missing keys silently fall back to the raw key. This makes it easy to ship untranslated strings unnoticed. Add a CI check that scans lang/*.php (and Blade) for keys and verifies they exist, or run an import diff and fail on new keys. Also watch for the package's behavior on placeholder mismatches — :name vs :Name — which often isn't validated.

Performance. DB-backed translation lookups without caching turn a single page render into many queries. Enable the cache, and warm it in a deploy step. If you're on a read replica, ensure translation writes go to the primary and bust the cache after the write is committed, not before.

Extension points to know. The usual seams are: the loader binding (swap it for your own if you need custom precedence), the Translation model (add observers for audit logging), and the console commands (wrap them in your own artisan command for deploy scripts). Because dependents are essentially zero, there's no ecosystem of battle-tested integrations — expect to write the glue yourself.

Sourcing and version risk. At 3 stars and 0 dependents, treat this as "read the source before relying on it." Pin a specific version, check the latest release for compatibility with your Laravel/PHP versions, and keep a fallback path (the file-based loader) so you can disable the package without an outage. The payoff — editable translations without touching Blade — is real, but the operational burden is entirely on you.