Laravel Translation Laravel Package

Getting Started

3.0.0 is a substantial redesign of panelify/translation, so start by confirming the package was previously installed under an older vendor namespace — the move files to panelify/translation package change means your use statements and composer.json entry likely need updating before anything else works.

First steps:

1. Install/upgrade the package and publish the new migration and config (php artisan vendor:publish). The migration has been rewritten with new indexes for "any database", so re-publish rather than assuming your old migration is compatible.
2. Check your models. The HasTranslation trait is the primary day-to-day entry point for translatable models. The old TranslationContract interface is gone — if you typed against it anywhere, swap to the trait (or drop the type hint entirely).
3. Run the new tests the package ships (php artisan test --filter=Translation) to confirm the redesigned requests and rule behave as expected on your Laravel version. The release adds test coverage for HasTranslation, resource files, requests, and the rule — a good reference for the intended API.
4. Pick your first use case: either model translations via HasTranslation / HasDynamicTranslation, or validating translation input with TranslationFieldExistRule in a form request.

Implementation Patterns

Model translations. Add HasTranslation to any Eloquent model that needs translations. Use HasDynamicTranslation instead when translation keys are discovered at runtime rather than declared upfront — this trait was reworked in 3.x, so treat its behaviour as new rather than a drop-in.

Form requests. The redesigned request classes (TranslationTypeObjectRequest, TranslationArrayRequest, MultiTranslationTypeObjectRequest, MultiTranslationArrayRequest) cover four common input shapes: a single typed object, an array of translations, and their multi-translation counterparts. Extend the closest one rather than hand-rolling validation in controllers.

Validation. TranslationFieldExistRule is a custom rule for validating that a translation field exists. Use it directly in your own rules arrays when you don't need the full request scaffolding.

Events. TranslationForgetEvent fires on forget operations — hook listeners here for cache invalidation or audit logging.

Testing. Extend the new base test case that registers the language service provider, so translated fields resolve correctly in tests instead of silently returning unmodified keys. Use the new TranslationFactory for seeding translation records.

Files vs database. The package now handles document files alongside database-driven translations. If your app ships static translation files, keep them in the expected resource path (revised in 3.x) so the resource loader picks them up.

Gotchas and Tips

• Namespace move is the biggest upgrade trap. Anything referencing the old vendor path will fail after upgrading. Grep your app/, config/, and tests for the old namespace.
• TranslationContract removal is breaking. If you bound an implementation or used instanceof/type hints against it, refactor to the HasTranslation trait. There is no shim.
• Migration changes are breaking too. The new migration adds indexes and is rewritten for cross-database compatibility. Don't assume you can roll it back cleanly on production — plan a fresh migration or manual index additions.
• is_subclass_of ↔ class_uses_recursive flipped twice during the release. If you're on a 3.0.0 pre-release, ensure you're on the final build; trait-detection behaviour differs between them and affects which traits are recognised on models.
• Exception messages are now translatable. If you were asserting against hardcoded exception text (e.g. disallow_field), update your tests — the release added translation keys for these exceptions.
• HasDynamicTranslation behaviour changed. Re-test any screen that relies on dynamic key discovery; the old test translation was removed, so old passing tests may no longer reflect real cases.
• Debugging translation misses. When a key returns untranslated, check in this order: language service provider registered, migration run with new indexes, trait present on model, then resource file path.
• Extension point: the new base test case shows the intended wiring for the language service provider — mirror that in your own test base class if you have one.