Sulu Translations Bundle Laravel Package

Getting Started

This is a Sulu CMS bundle (Symfony-based), not a Laravel package — there is no service provider or config/app.php entry. If you're a Laravel developer, map your instincts as follows: composer require → config/bundles.php, .env → config/packages/*.yaml, php artisan migrate → bin/console doctrine:migrations:migrate, php artisan cache:clear → bin/console cache:clear.

Minimal steps:

1. composer require tailrdigital/sulu-translations-bundle
2. Register Tailr\SuluTranslationsBundle\SuluTranslationsBundle in config/bundles.php (after SuluBundle).
3. Import the bundle's routing/admin config in config/routes/sulu_admin.yaml and config/packages/sulu_admin.yaml as instructed by the bundle README.
4. Run migrations, then bin/console cache:clear and rebuild the admin UI (bin/console sulu:admin:update-build or your usual asset build).
5. Log into /admin → Settings → Translations.

Look first at src/Resources/config/ (services, Doctrine mapping) and the entity/repository pair — that tells you the storage model, which is what everything else hinges on. Your first real use case: replace a hardcoded messages.en.yaml key with a DB-backed translation key, render it in Twig ({{ 'my.key'|trans }}), and confirm it resolves per locale.

Implementation Patterns

Admin-driven translation workflow. Translation keys are created and edited in the Sulu admin rather than in XLIFF/YAML files. The typical team pattern: developers create keys + English source text, translators fill the rest in the admin, and no deploy is needed to ship copy changes.

Consuming keys in templates. Keep using Symfony's translator in Twig/PHP — the bundle supplies the values. Verify the domain/loader ordering in config/packages/translation.yaml so DB-backed keys take precedence over (or fall back to) file-based ones in the same domain.

AI translation (new in 0.4.0). The release activates Sulu's AI translation feature for translation keys. Pattern:

• Configure the Sulu AI translation provider (API key in .env, provider config in config/packages/sulu_ai.yaml) — without a working provider the action is unavailable, not merely broken.
• In a translation key's form, trigger AI translation to fill empty target locales, then review before saving.
• Treat it as a first-pass draft: bulk-seed new locales, then have a human sign off. Don't let it silently overwrite existing human translations — verify behaviour on a non-empty field before wiring it into a release process.

Seeding / fixtures. For reproducible environments, create translation keys programmatically via the bundle's repository or a Doctrine fixture rather than clicking through the admin. Pair this with your normal doctrine:fixtures:load step in CI and local bootstrap.

Importing existing copy. If you're migrating from file-based translations, script the import (parse YAML/XLIFF → insert keys) and keep the source files in VCS until you've confirmed parity. This makes rollback trivial.

Permission-aware integration. Translation keys live behind Sulu security contexts. Grant view/edit contexts to the translator role; the AI action respects the same edit permission, so a role without it won't see the button — a common "the feature is missing" false alarm.

Gotchas and Tips

• Pre-1.0 versioning. At 0.x, minor bumps (0.3 → 0.4) can carry breaking changes. Pin the version in composer.json and read the changelog before every upgrade; 0.4.0 itself looks additive, but the pattern is worth internalising.
• It's Symfony, not Laravel. Bundle registration, container autowiring, and config caching all behave differently from a Laravel package. config:dump-reference sulu_translations (or the bundle's config tree) is your friend for discovering options.
• AI feature has prerequisites. 0.4.0 depends on Sulu's AI translation support being present and configured. On older Sulu versions or with an unconfigured provider, expect a missing button rather than an error — check sulu_ai/translation config first before filing a bug.
• Fallback locales mask gaps. If your locale fallback chain is configured, a missing translation may render the fallback's text. AI-filled values can therefore look "already done" — test with fallbacks disabled when auditing completeness.
• Caching. Translation values are cached. After bulk imports or AI batches, clear the cache (bin/console cache:clear, and your HTTP/production cache layer) or you'll chase phantom stale strings.
• Don't hand-edit the DB. Bypassing the repository/entity layer skips cache invalidation and any normalisation the bundle applies.
• Debugging. Use the Symfony profiler's Translation panel to confirm which loader (DB vs file) supplied a given key, and bin/console debug:container | grep -i transl to find the bundle's services. For AI calls, log the HTTP client traffic.
• Cost and review. AI translation is billed per request by the upstream provider — batch sensibly, gate it behind a translator role, and never wire it into an unattended deploy step.
• Extension points. Override admin templates via Sulu's template override mechanism, and decorate the bundle's services in config/services.yaml to add validation or audit-logging around translation saves rather than forking the bundle.