Translator Bundle Laravel Package

Getting Started

First, the reality check for a Laravel developer: this is not a Laravel package. It's a Symfony 2-era bundle from the Kunstmaan CMS stack (last release 2014-08-01, PHP 5.x, AppKernel registration, Sonata-style admin). There is no service provider, no config/ publish tag, and zero dependents. You cannot composer require it into a Laravel app. Evaluate it as a reference implementation of a pattern — DB-backed, admin-editable translations with a cached read path — not as a dependency.

If you are on a Kunstmaan CMS install (the only place it actually runs):

1. composer require kunstmaan/translator-bundle (pin to a Symfony 2.x-compatible tag).
2. Register in AppKernel.php after KunstmaanAdminBundle, and import the bundle's admin routing.
3. Run doctrine:schema:update (or the bundle's migration) to create the translation table.
4. Log into the admin → Settings → Translations.

Where to look first, in this order:

• Resources/config/services.yml — the bundle's whole trick lives here: it decorates/overrides the translator service with its own implementation.
• Entity/Translation.php + Repository/TranslationRepository.php — the storage model (locale, domain, key, value).
• Translator/ — the decorator that reads from the repository rather than only from translations/*.yml.
• Command/ — import/export commands (check bin/console list for the exact names).
• The admin controller — the CRUD surface editors actually touch.

First use case: replace a hardcoded key. In Twig, {{ 'checkout.vat_note'|trans }} still works unchanged; the string now resolves from the DB row an editor creates in the admin, with the file catalogue as fallback. That drop-in compatibility is the reason to consider the pattern at all.

Laravel equivalent you'd actually ship:

composer require spatie/laravel-translation-loader
php artisan vendor:publish --provider="Spatie\TranslationLoader\TranslationServiceProvider"
php artisan migrate

Then add a Filament/Livewire resource over the language_lines table. Same architecture, modern runtime.

Implementation Patterns

Decorate, don't replace. The bundle's design keeps |trans untouched by swapping the translator service; nothing in templates or PHP changes. Replicate this by registering a DB-backed loader before the file loader, not by rewriting your call sites.

File-first, DB-second migration. Don't point the DB at an empty table. Seed from your existing YAML so every current key resolves before editors start adding new ones. The import command does this; in Laravel, iterate lang/**/*.php into language_lines.

Export is your release gate. The bundle ships an export command that writes DB content back to files. Do this in CI (or at minimum before a deploy) so:

• translation changes get code review like any other change,
• new environments can be re-seeded deterministically,
• you can roll back a bad editorial edit.

Limit the blast radius with manage_domain. Configure only your application domain (e.g. messages) as editable; leave vendor/bundle strings in files. Otherwise editors can silently break third-party UI text and you'll never get it back.

# Kunstmaan-era config shape (verify against your pinned version)
kunstmaan_translator:
    enabled: true
    manage_domain: [messages]
    cache: true

Deployment workflow. Migrate the schema → import/seed content → warm the translator cache → run debug:translation-style checks for missing keys. The DB is content, so treat it like you'd treat CMS pages: seedable, exportable, never the source of truth for a code review.

Laravel-side pattern:

// config/translation-loader.php
'translation_loaders' => [
    DatabaseTranslationLoader::class,
    FileLoader::class,   // fallback order matters
],

Plus a translations:import / translations:export artisan pair, and cache busting in the model's saved/deleted events.

Gotchas and Tips

• Cache invalidation is the whole operational risk. The "retrieved on the most efficient way possible" claim depends entirely on a warmed cache. With APC on multiple web nodes, an admin edit busts one node and leaves the rest stale. Use a shared cache (Redis/memcached) or accept periodic stale strings.
• Service decoration is invasive. Anything that compiles catalogues outside the normal request cycle — cache warmup, translation debug commands, console commands — may bypass the DB entirely. Verify with debug:container translator and by running your missing-key check in the prod environment.
• Unbounded query growth without cache. One query per locale × domain per request is fine when warm, expensive when cold; queue workers and cron jobs each pay the warmup cost.
• Fallback chains must be explicit. DB hit → file catalogue → fallback locale → raw key. Document it, because editors will assume "empty string" means "no text" when it actually means "fall through to the file", and vice versa.
• Schema vs. content in migrations. The translation table is schema; its rows are data. Never let a doctrine:schema:update/migrate:fresh silently wipe editorial content in staging.
• Stable keys are a contract. Renaming a key in code orphans the DB row and the UI shows the raw key. If you must rename, write a data migration, not a find-and-replace.
• Don't use it for vendor strings and don't use it for anything with interpolation-sensitive validation messages unless you're prepared for editors dropping :count or {name}. Add a placeholder validator on save — this is the single most common production bug in DB-backed translation systems.
• Extension points worth adding: an updated_by/updated_at audit column, a "missing keys" report generated from a static scan of templates, and per-key context notes. The 2014 bundle predates all of this; a modern Laravel port should bake it in.
• Maintenance verdict: 50 stars, 0 dependents, no release since 2014 — treat as abandoned. The opportunity (the high opportunity score is telling) is in the gap: spatie/laravel-translation-loader plus a Filament translation resource gives you 90% of this bundle's value on a supported stack, and lets you own the cache-invalidation story instead of inheriting a Symfony 2 one.