Laravel Translatable Laravel Package

Product Decisions This Supports

• Localization roadmap sequencing. This package lets a single Eloquent model carry translations as a JSON column, so we can ship a first-class multi-locale experience without a schema migration per language. That directly informs whether we commit to "launch in N markets this year" or gate localization behind a broader platform re-architecture.
• Build vs. buy for translation infrastructure. It replaces a self-built translation table/pivot layer with a maintained, MIT-licensed trait. The build-vs-buy decision becomes: adopt the package now (days of effort), reserve translation management systems (TMS) or dedicated translation tables for when we outgrow it.
• Content model decisions. Because translations live on the model row, we can decide per-entity which fields are localizable. Fields declared via #[Translatable(...)] (or $translatable) make the set of translated fields an explicit, reviewable product artifact rather than a hidden database convention.
• Feature scope for editorial and admin tooling. setTranslation, getTranslation, and getTranslations give us a clean API for "edit each locale separately" admin screens, including nested JSON fields (meta->description) for structured content like SEO metadata — a common source of "we forgot to translate the meta description" bugs.
• Localized browsing and filtering requirements. whereLocale, whereLocales, whereJsonContainsLocale(s) with like operands let us scope content by market in listings and search. This determines whether market-scoped catalogs, localized landing pages, and per-locale availability filters are a small feature or a separate search service.
• Market expansion prioritization. Since adding a locale is largely a content and copy operation rather than an engineering one, we can prioritize markets by commercial signal (traffic, demand, partner requests) instead of by engineering capacity — a meaningful change to how we rank roadmap bets.
• Risk decision on data portability. JSON-per-row means locale data is co-located with the entity, which simplifies backups, exports, and GDPR deletion for content records, but constrains per-locale indexing and reporting. That trade-off should be an explicit, documented decision rather than an accidental one.

When to Consider This Package

Consider it when most of the following hold:

• The product is a Laravel/PHP application already using Eloquent, with a modest set of localizable fields (names, titles, descriptions, slugs, SEO metadata) on content-like models.
• We need to ship a small-to-moderate number of locales (roughly 2–10) and translation volume per record is low enough that a JSON document per row is natural.
• Translation is content-oriented, not workflow-oriented: no per-locale approval chains, per-locale permissions, translation memory, or vendor/TMS handoffs required in v1.
• The team is small and we want to avoid a second table and join logic for every localized field — fewer moving parts, faster iteration, easier onboarding.
• We benefit from in-model locale filtering for listings (market-scoped catalogs, localized feeds) rather than needing a dedicated search index.
• We want an actively maintained, MIT-licensed dependency with docs, changelog, releases, and current Laravel/PHP support — low legal and upgrade risk.

Look elsewhere when:

• We need per-locale workflow, permissions, or audit trails (who approved the Dutch copy, when). Dedicated translation tables or a TMS integration model this far better.
• We need database-level uniqueness or constraints per locale (e.g., one unique slug per language). JSON columns make this awkward; a translations table with (locale, slug) indexes is the honest answer.
• Reporting and analytics must group, sort, or aggregate by translated value at scale, or the JSON columns would be hit by heavy filters and full-text search.
• We expect many locales with sparse coverage, where a JSON document per row grows unwieldy and query plans degrade.
• The stack isn't Laravel or we're planning to extract content into a headless CMS — the package is firmly Eloquent-coupled.
• We require content versioning/draft states per locale as a first-class product requirement.

How to Pitch It (Stakeholders)

To executives: This is a small, free (MIT), well-maintained open-source component that makes our Laravel product multilingual without new database tables or infrastructure. It converts "launch in a new market" from an engineering project into a content project — copywriting and review instead of schema changes and migrations. It is used widely, is current with the latest Laravel and PHP releases, and is maintained by Spatie, a long-standing vendor in the PHP ecosystem. The commercial effect is that market expansion can be prioritized by demand rather than by engineering bandwidth, and the cost of adding locale three or four is close to zero on the engineering side.

To engineering: It's a single trait plus a #[Translatable] attribute on the model; translations persist as JSON on the row, so no joins and no extra tables. We get locale-aware accessors, per-field setters and getters, nested JSON key support for things like meta->description, and query scopes (whereLocale, whereJsonContainsLocale with like) for market-scoped listings. Configuration covers null/empty-string handling. The code surface we depend on is small and well documented, releases are frequent, and Laravel 13 support is already in. Effort is measured in days, not sprints.

To product and content leads: Editing a record means editing each language side by side through a simple API, including structured fields like SEO metadata, which removes a common class of "untranslated metadata" defects. The main constraint to plan around: this is a content-storage tool, not a translation-management tool. If we later need per-language approval workflows, per-locale permissions, or translation vendor integrations, we should expect a follow-on project — and we should say so now so it doesn't surface as a surprise during a market launch.