Translation Bundle Laravel Package

Getting Started

First, the framework mismatch. gregooze/translation-bundle is a Symfony bundle — a fork of lexik/translation-bundle updated for Symfony 3.3 — so it does not drop into Laravel. There is no service provider, no facade, and it depends on Doctrine ORM plus the Symfony DI container, routing, and translation component interfaces. If you are on Laravel, the equivalent is spatie/laravel-translation-loader (DB-backed translations) plus a Filament/Nova CRUD screen; treat this bundle only as a reference design. The rest of this assessment assumes you are working in a Symfony 3.3 codebase or evaluating the fork for a legacy app.

Installation (Symfony 3.3):

composer require gregooze/translation-bundle

Register in app/AppKernel.php:

new GregHubs\TranslationBundle\GregoozeTranslationBundle(),

Note the namespace may still be Lexik\Bundle\TranslationBundle if the fork kept it — check composer.json autoload.psr-4 before wiring the kernel class name. This is the single most common first failure.

Minimal config in app/config/config.yml:

gregooze_translation:
    managed_locales: ['en', 'fr']
    fallback_locale: en
    storage:
        type: orm

Then create the schema:

php app/console doctrine:schema:update --force
# or generate a migration — preferred, see Gotchas

Where to look first: the bundle's Resources/config/ for service ids and default config keys, Entity/Translation.php for the storage shape (translation_key, locale, domain, text), and Command/ for the import/export commands. Those three directories tell you 80% of how the thing behaves.

First use case: import your existing messages.en.yml files into the DB, edit them in the bundle's web grid, then export back. That round trip is the core value — non-developers get a UI, developers keep flat files in git.

php app/console lexik:translation:import --force
php app/console lexik:translation:export

Secure the UI immediately. The bundle ships routes (typically under /_translation) with no authentication. Add a firewall or role check in security.yml before the first deploy — this is the #1 real-world vulnerability with this package.

Implementation Patterns

Database as source of truth, files as build artifacts. The pattern that actually holds up: translators work in the UI against the DB, and CI runs lexik:translation:export on deploy to regenerate app/Resources/translations/*.yml. Developers never hand-edit the exported files. If you keep both as editable sources, they will diverge and you will spend a day reconciling.

Import/export in the deploy pipeline. Run import once to seed, then export-only in CI. A useful diff gate: export to a temp dir, git diff --exit-code, and fail the build if translation files are stale relative to the DB. That catches "translator edited prod only" drift.

Seed missing keys automatically. lexik:translation:create-missing (name varies across versions — verify via app/console list) scans templates for trans/|trans usage and inserts missing keys. Wire it into a nightly job so new UI strings appear in the translators' queue without a developer filing a ticket.

Per-environment locale management. Keep managed_locales small in dev (['en']) and full in prod. Loading ten locales into the grid makes the UI noticeably sluggish; nobody needs to browse Hungarian in their local sandbox.

Cache strategy. The bundle exposes a cache-clean command and an auto_clean_cache option. In production, prefer explicit cache invalidation in your deploy script (lexik:translation:clean-cache) over auto_clean_cache: true, which can thrash the cache during bulk edits and is a hidden latency source under load.

Integrate with a translation workflow, not a spreadsheet. Export to XLIFF and hand it to translators; import the result. Avoid having translators touch the DB directly — audit trails are minimal and there is no per-user history.

Gotchas and Tips

Fork risk is the headline. Zero stars, zero dependents, and "adapted for SF3.3" — a Symfony version that reached end-of-life in 2018. You are inheriting an unmaintained fork of an unmaintained fork. Before adopting, check: does it still reference deprecated Controller service patterns, static getName(), or $this->get() calls removed in SF4? If your plan is ever to upgrade to Symfony 4/5/6, budget for forking further or migrating to upstream lexik/translation-bundle (which does support newer Symfony) — the fork's only real contribution is likely composer constraints.

Namespace and bundle-class drift. Forks frequently leave the original namespace intact and only change the package name. Confirm autoload.psr-4 and the kernel class before debugging "class not found" for an hour.

Schema updates will bite you. doctrine:schema:update --force in dev is fine; in prod it will silently drop or alter columns on a table your application reads at runtime. Generate a migration, review the SQL, and check indexes on (translation_key, locale, domain) — the default entity is queried heavily and missing indexes show up as slow page loads once you pass a few thousand keys.

Export overwrites formatting. Exported YAML is regenerated from the DB, so comments, ordering, and quoting in your hand-written files vanish. If you have curated messages.en.yml with explanatory comments, keep that file out of the export scope or accept the loss.

Duplicates and orphan keys. Importing the same keys from multiple domains or with trailing whitespace in the key creates near-duplicates that the grid cannot distinguish. Normalize keys on import and run a periodic SELECT translation_key, locale, domain, COUNT(*) ... HAVING COUNT(*) > 1.

Fallback locale confusion. fallback_locale affects UI display for missing entries but does not necessarily change what the Symfony translator returns. Test a missing key explicitly rather than assuming.

Extension points. The storage config accepts a custom class implementing the storage interface — useful if you must keep translations in Redis or an external TMS. Templates are overridable via Resources/GregoozeTranslationBundle/views/ in your app, which is the cleanest way to add your own branding, role checks, or a "pending review" column without touching vendor code.

Debugging tip. When a translation doesn't update in the browser, check three layers in order: DB row exists → bundle cache cleared → Symfony's own translation cache (var/cache/prod) rebuilt. Most "it didn't save" reports are the third layer.

Do not use it as your only audit trail. There is no change history. If compliance matters, add a Doctrine listener on the Translation entity writing to an audit table — it's a ten-line listener and saves you later.