Config Bundle Laravel Package

Getting Started

• Install with composer require <vendor>/<package>. Note that v1.0.1 tightens the constraint on translation-bundle, so the bundle is now pulled in as a required dependency rather than something you add yourself. Run composer why translation-bundle after install to confirm which version resolved and which package pulled it in.
• First place to look: config/<package>.php (publish with php artisan vendor:publish --tag=<package>-config), then the package's resources/lang / lang directory to see which translation namespace it registers.
• Publish the language files before writing any UI code: php artisan vendor:publish --tag=<package>-translations. If you skip this, the package falls back to its bundled strings and you cannot override them per-locale.
• First use case: render the package's default component/route with your app set to a non-English locale and confirm strings resolve through the bundle namespace (e.g. <package>::messages.key) rather than showing the raw key.

Implementation Patterns

• Override, don't fork. After publishing, keep your edits in lang/vendor/<package>/<locale>/*.php. Laravel's translator checks the application lang path before the package namespace, so your overrides win without touching vendor code. On the next upgrade, re-publish with --force only into a scratch directory and diff, rather than overwriting live overrides.
• Pin the bundle in your root composer.json if you need a specific version. Because v1.0.1 now declares the requirement, your root constraint becomes the tie-breaker in resolution; declaring it explicitly makes composer update deterministic across environments.
• Locale switching middleware. Set App::setLocale() early (a SetLocale middleware reading the session/user preference) so the bundle resolves before the controller renders. Anything that caches translated HTML per-request will otherwise leak the previous locale.
• Multi-tenant / per-locale testing. In Pest/PHPUnit, wrap translation assertions with $this->withSession(['locale' => 'de']) or App::setLocale('de') and assert on the resolved string, not the key — this catches missing keys introduced by a bundle bump.
• CI: commit composer.lock, and let a dependency bot open PRs for translation-bundle patch bumps. Treat those as low-risk but run the translation assertion suite anyway; string changes are silent failures.
• Caching after deploy. Translations and config are cached in production; add php artisan config:cache and any language-cache step to your deploy script after publishing, and clear before publishing, never the other way around.

Gotchas and Tips

• The v1.0.1 change is a constraint change, not a code change. The practical risk is Composer resolution: if your app (or another package) pins an older translation-bundle, composer update will now fail with a conflict where it previously succeeded. Run composer update --with-dependencies in a branch and read the conflict output before merging.
• Silent fallback locale. When a key is missing in de, Laravel falls back to config('app.fallback_locale') without error. During localisation work, temporarily set fallback_locale to a nonsense value like xx so missing keys surface loudly instead of shipping English to German users.
• Stale published files. Published translations are a snapshot. After a bundle upgrade, new keys will resolve from the vendor copy while your overrides remain — usually fine, but you can end up with a half-translated UI. Diff the vendor lang dir against your published copy on each minor bump.
• Namespace mismatch. If strings render as raw keys, check that the package's registered translation namespace matches what the views call. php artisan about and Lang::getLoader()->namespaces() (tinker) confirm what's registered.
• Config cache staleness. config:cache freezes the locale list and any package config. A .env locale change after caching has no effect — a classic "works locally, wrong language in staging" cause.
• Extension points: the translator's loader is swappable, so a database-backed translation driver is the clean way to add runtime editing without hacking the package. Also check for a package-level translator or locale_resolver binding in the service provider before writing your own.