Craftable Translatable Laravel Package

Getting Started

• Install with composer require <vendor>/<package> and confirm the service provider is auto-discovered; nothing needs publishing for the 2.0.1 upgrade path.
• Start with the README — it was updated in this release and is the fastest way to see the two entry points most apps need: the Translatable / HasTranslations model trait and TranslatableFormRequest for per-locale validation.
• First use case: make one Eloquent model translatable (add the trait, define the translated attributes, migrate a JSON/text column per locale), then create a form request that extends TranslatableFormRequest so a single request validates { "en": {...}, "fr": {...} } payloads.
• Verify behaviour with a feature test hitting a controller that uses the form request, asserting both that validation rules apply per locale and that $model->toArray() returns the locale-resolved values your API expects.

Implementation Patterns

• Model layer: add the trait and declare translated attributes once; read/write through the current locale and use explicit locale accessors for admin screens that edit several locales at a time. getLocale() resolving from the container (changed in 2.0.1) means locale resolution now follows container bindings — useful when you swap locale services in tests.
• Serialization: HasTranslations::toArray() is the boundary your JSON resources sit on. Prefer letting it produce the locale-flattened array and layer API resources on top, rather than re-implementing translation picking in each resource.
• Validation: extend TranslatableFormRequest and return rules keyed by locale, e.g. ['en' => ['title' => 'required|string']]. Mixing array rules and plain string rules ('email' => 'required|email') is supported — the 2.0.1 guard on the is_array($rule) branch fixes the case where array_search() was previously reached with a string rule.
• Workflow tip: centralise locale configuration (Translatable::getLocales() / config) and drive both validation loops and admin form generation from it, so adding a locale is a one-line change rather than a search-and-replace.
• Integration: when importing/exporting data, loop locales explicitly instead of relying on the ambient app locale — this keeps queue jobs and console commands deterministic.

Gotchas and Tips

• Upgrade risk is low but not zero. 2.0.1 adds parameter types to the closures inside TranslatableFormRequest, HasTranslations::toArray() and Translatable::getLocales(). Because PHP allows parameter-type widening in subclasses, untyped overrides are still compatible — but any code that reflects on those closures, or tightly typed overrides that assume no parameter types, should be re-run through the test suite.
• Behavioural bugfix worth knowing: previously, string validation rules could reach array_search() in rules() and trigger warnings/errors on PHP 8. If you had silently worked around this (e.g. by splitting translatable and non-translatable rules into separate requests), you can now collapse them into one request.
• app() vs container: if you have tests that fake or bind the application/locale resolver, HasTranslations::getLocale() now honours the container — expected, but assert locale-dependent output in tests that stub bindings.
• Debugging translations: dump toArray() and the raw attribute to distinguish "translation missing" from "fallback locale applied"; most confusion comes from fallback configuration rather than the trait itself.
• Database/CI signal: the package now runs its matrix over PostgreSQL and MariaDB with a healthchecked docker-compose (dedicated laravel DB user). If you develop against these engines, mirror that setup locally rather than assuming MySQL-only behaviour for JSON/column types.
• Extension points: subclass the form request to inject shared rule fragments and messages, and override locale discovery rather than editing vendor code — closures are now typed, so keep your overrides at the same or wider parameter types.