Getting Started

whitedigital-eu/translation-bundle is a PHP translation bundle (Symfony-style Bundle + DI extension) that sits on top of your translation storage. Release 0.2.0 is a single feature release — feat: lexik (PR #4) — which adds a Lexik integration path (LexikTranslationBundle-style translation providers/loaders). There are no removals or deprecations listed between 0.1.2 and 0.2.0, so it is a drop-in minor bump, but it does introduce a new optional dependency surface you should verify before upgrading.

Steps:

Pin the new minor explicitly — this is a 0.x package, so ^0.2 is the only safe constraint:
```
composer require whitedigital-eu/translation-bundle:^0.2
```
Look here first, in this order:
- composer.json → check type (symfony-bundle), require, and suggest/conflict entries for the Lexik package. That tells you whether 0.2.0 hard-requires Lexik or treats it as optional.
- src/ → the new Lexik adapter/loader classes (the bulk of PR #4).
- DependencyInjection/Configuration.php + *Extension.php → the new config keys added for Lexik.
- Resources/config/*.xml|yaml → service wiring and any conditional (class_exists) service definitions.
- README.md / UPGRADE*.md → the documented enablement flag.
First use case: you already have translations in a Lexik-style store (DB table or Lexik-format resource files) and you want this bundle to read them rather than duplicate them.

Symfony wiring (typical for a bundle of this shape):

// config/bundles.php
return [
    WhiteDigital\TranslationBundle\TranslationBundle::class => ['all' => true],
    // Lexik bundle only if you actually use it
];

# config/packages/white_digital_translation.yaml
white_digital_translation:
    lexik:
        enabled: true
        # provider/loader ids, domain + locale mapping go here

Laravel note: there is no Laravel service provider shipped, so "getting started" in a Laravel app means registering the bundle's services yourself in a small package provider (see below) or — more realistically — using the bundle's loader classes standalone.

Implementation Patterns

1. Adopt the Lexik path only where you already own Lexik data

The 0.2.0 feature is an interoperability adapter, not a replacement storage engine. The clean pattern is: keep Lexik as the source of truth, register this bundle's loader as an additional translation resource, and let it normalise domains/locales for you.

2. Register the bundle's classes in a Laravel provider

Since the package targets Symfony's container, bridge it manually:

public function register(): void
{
    $this->app->singleton(\WhiteDigital\TranslationBundle\Lexik\LexikTranslationLoader::class, function ($app) {
        return new \WhiteDigital\TranslationBundle\Lexik\LexikTranslationLoader(
            $app['config']->get('translation.lexik.domains', []),
        );
    });
}

Guard against the optional dependency so the app still boots without Lexik installed:

if (!class_exists(\Lexik\Bundle\TranslationBundle\LexikTranslationBundle::class)) {
    return; // lexik integration unavailable, fall back to file loaders
}

3. Wire it as a translation resource, not a runtime lookup

Prefer preloading/importing over per-request resolution. A console command that imports Lexik messages into the app's normal lang/ catalogue keeps hot paths free of extra container lookups and survives php artisan optimize.

4. Use it in warmup / export jobs

The bundle's natural workflow is bulk: export translations, warm caches, sync locales. Run it in CI or a scheduled job:

Schedule::command('translations:import --lexik')->hourly()->onOneServer();

5. Domain and locale mapping as configuration

Keep locale/domain aliasing in config (the extension's config tree) rather than in code, so environment-specific Lexik setups don't require patches. Treat en_US → en style fallbacks as explicit config, not implicit behaviour.

6. Test against a fixed fixture set

Because 0.2.0 only adds the Lexik integration, a small fixture covering: message found, message missing, fallback locale hit, and unknown domain is enough regression coverage for the upgrade.

Gotchas and Tips

0.x semver: 0.2.0 is a minor bump, which under semver means breaking changes are permitted at this major version. Pin ^0.2 and read the diff of PR #4 rather than assuming drop-in compatibility.
Optional vs required dependency: the release note says only "feat: lexik". Confirm in composer.json whether Lexik is a hard require (bloats your dependency tree) or a suggest/conditional service. If hard-required, 0.2.0 may pull a Symfony-heavy package into a Laravel app.
Guard with class_exists: if the bundle registers Lexik services unconditionally, container compilation will fail without Lexik installed. Check for a conditional service definition; if absent, that is the first thing to patch or report upstream.
Caches diverge: Symfony's bin/console cache:clear is not php artisan optimize:clear. After changing translation config in a Laravel app you must clear Laravel config/route/view caches and any bundle-level cached catalogue, or you'll debug phantom stale strings.
Locale/fallback mismatch: Lexik locale codes and Laravel's config('app.fallback_locale') frequently disagree (en_GB vs en). Mismatches manifest as missing keys, not exceptions — test the fallback path explicitly.
Container coupling: don't expect facades or Laravel helpers. Anything touching ContainerInterface, tagged services, or Bundle classes will need a manual bridge; keep that bridge to one small provider so it's replaceable.
Debugging: for Symfony, bin/console debug:container <lexik-service-id> and debug:config white_digital_translation are the fastest checks. In Laravel, dump the resolved loader instance from the container and assert the domain map is what you expect before blaming the adapter.
Extension points worth knowing: translation loaders, the bundle's DI extension config tree, and (if present) any export/import commands. These are the stable seams — hook there rather than subclassing internal adapter classes, which are the most likely thing to change in the next 0.x.
Upgrade checklist: diff Resources/config + DependencyInjection/Configuration.php between 0.1.2 and 0.2.0; run the import command against a copy of prod translation data; only then roll forward.

Translation Bundle Laravel Package