Sonata Translation Bundle Laravel Package

Getting Started

• This is a Symfony/Sonata bundle, not a Laravel package. There is no config/app.php provider list or php artisan vendor:publish. It plugs into sonata-project/admin-bundle, so you must already have a working SonataAdmin install (an Admin class, sonata_admin.yaml, security roles, a logged-in admin user) before this adds anything.
• Verify compatibility first. Open the repo's composer.json and check the symfony/* and sonata-project/admin-bundle constraints. With 1 star, 0 dependents, and a NOASSERTION license, treat it as an untested fork. Pin the exact commit/tag and test against your installed Sonata version before committing.
• Install: composer require salim/sonata-translation-bundle. If Composer rejects the name (the lineage is historically ibrows/sonata-translation-bundle), add a VCS repository entry pointing at the GitHub URL and require the actual package name from its composer.json.
• Register the bundle in config/bundles.php (Flex) or AppKernel::registerBundles(), after SonataAdminBundle and the translator-related bundles.
• Import routing — add a sonata_translation: (or extension alias) entry in config/routes.yaml/routing.yml pointing at the bundle's Resources/config/routing.*. Confirm the import name by reading DependencyInjection/*Extension.php and the routing filename.
• Configure under the bundle's root key (likely sonata_translation: or ibrows_sonata_translation:). Copy from DependencyInjection/Configuration.php rather than the README — the README is effectively the only "docs" and may be stale.
• First use case: log into /admin, find the new "Translations" group in the sidebar, filter to one domain/locale (e.g. messages/en), edit a single key, save, then bin/console cache:clear and confirm the change renders. That round-trip tells you whether storage, permissions, and cache are all wired correctly.

Implementation Patterns

• Admin catalog editing (the core workflow). Use the provided Admin class to list translation keys per (domain, locale), filter untranslated entries, and edit values in Sonata's list/edit screens. Typical flow: translator filters by locale → edits → saves → cache is invalidated.
• Inline/front-end edit mode (if this fork retains it). Enable translation edit mode for a specific role, walk the page, click a string, edit in place, save. Gate this behind a staging environment and a dedicated role — never expose it on public traffic.
• Storage strategy. File-based write-back targets translations/<domain>.<locale>.<format>; DB-based needs a custom loader and a warmup step. Pick one deliberately: file-based plays nicely with the native translator but requires writable directories, while DB-based survives read-only deploys but needs its own caching.
• Warmup/deploy. After edits, run bin/console cache:clear (and cache:warmup in prod). Better: hook a post-save listener to invalidate the translator cache so editors see results immediately instead of filing "it didn't save" tickets.
• Seed then edit. Use bin/console translation:extract / translation:update to add new keys, then let editors fill values in the admin. Keep the format aligned with what the extraction command emits (XLIFF vs YAML vs PHP) or your diffs will be noisy on every save.
• Multi-domain setups. Define separate admins/filters per domain (messages, validators, admin) and scope editor roles per domain so product copy and validation strings don't collide.
• CI/CD. Treat translation files as source-controlled artifacts. Add a CI diff check that fails on unexpected reformatting, and always run the cache-clear/warmup step in the deploy pipeline.

Gotchas and Tips

• Maintenance risk. 1 star, 0 dependents, NOASSERTION. Treat it as an abandoned lineage; read the source, pin the commit, and plan to fork or vendor it rather than trusting the README.
• Sonata version drift. SonataAdmin 4.x/5.x changed AbstractAdmin, datagrid, and lifecycle APIs. Old bundle code often fails at container compile time with "method not found" or missing service arguments. Check every services.xml reference against the installed Sonata version.
• Name mismatch. The Composer name (salim/...) and the historical namespace (ibrows/...) may not line up. The extension alias and route import name come from DependencyInjection/...Extension::getAlias() and the routing filename — not the package name. Grep those classes first.
• File permissions. Write-back runs as the web user (www-data/nginx). Ensure translations/ (or var/translations) is group-writable, or saves fail silently or throw "failed to open stream."
• Cache is the #1 confusion. Edits hit disk but prod serves the warm cache; the symptom is "my edit didn't save" when it did. In dev the translator cache is usually off, which masks the problem until deploy.
• Locale fallback. Editing en when the visitor resolves to en_GB may still show a fallback. Test with the exact locale and remember Symfony's chain (en_GB → en → default).
• XLIFF escaping. Values containing <, &, quotes, or ICU placeholders ({name}) can be mangled or break the parser. Round-trip a value with a placeholder and a <strong> tag before trusting mass edits.
• Security. The translation admin is effectively a CMS for every UI string. Restrict via sonata_admin security and ROLE_*, and expose inline editing only on staging.
• Decoration order. If you already decorate translator (DB loader, profiler), the bundle's decorator must run in the right order or the admin reads the wrong source. Check decorates: and decoration_priority.
• Debugging tools. Use bin/console debug:container <translator id> and bin/console debug:translation <locale> <domain> to see what's actually loaded, and the profiler's translation panel to confirm which file/key resolved.
• Extension points. The translator service id, the storage/persister service, and the Admin classes are the seams to override. Prefer subclassing the provided Admin and re-registering it in sonata_admin.yaml over patching the bundle.
• Exit strategy. Your data is just translations/*.xlf|*.yaml or a DB table — keep a plain export so you can migrate to symfony/translation plus a maintained editor (LexikTranslationBundle, Crowdin, etc.) without losing content if the bundle dies.