Laravel Translatable Laravel Package

Product Decisions This Supports

• Multilingual content strategy: Enables locale-specific versions of Eloquent models (posts, product pages, docs, CMS content) by storing each translation as a sibling record linked via locale_parent_id. This is record-level content translation, not UI string localization.
• Build vs. buy: Offloads the basic translation data model—migration macro, parent/child relations, translate(), getTranslation(), withLocale() scope—so the team can focus on editorial UX and fallback behavior rather than plumbing.
• Roadmap sequencing: Lowers the cost of piloting localization for one content domain. A PM can scope an MVP around a single model (e.g., blog posts) and expand only after validating performance and editorial workflow.
• Data architecture choice: Keeps translations normalized and queryable in SQL rather than buried in JSON columns—better for reporting, joins, indexing, and locale-filtered APIs.
• Configuration decisions: translatableConfig() (locale whitelist, column names) and translateAttributes() (derived/transformed fields) become explicit product/engineering agreements—e.g., whether a slug or SKU is copied, localized, or generated.
• Representative use cases: Localized product catalogs, CMS/news pages, regional documentation, and early international expansion where Laravel fit and speed matter more than enterprise translation workflows.

When to Consider This Package

• Adopt when:
  • You need simple, model-level translations where each locale is a full copy of the record.
  • Your stack is Laravel 10–13 / PHP 8.2–8.5 and you want a native trait, not an external service.
  • You prefer relational, queryable translation data over JSON blobs.
  • The localization scope is bounded (a handful of locales, moderate content volume) and the workflow is “editor creates a translated copy.”
  • Legal has approved AGPL-3.0 or the deployment model avoids its network-use copyleft obligations.
  • You can enforce query discipline: every listing, count, sitemap, search index, and API response must be locale-filtered.
• Look elsewhere when:
  • You need UI string localization—use Laravel lang files or a dedicated translation workflow.
  • You need field-level partial translations, translation memory, approval workflows, history/rollback, or machine translation.
  • You require many-to-many translation relationships (shared tags/categories) or complex fallback rules.
  • AGPL-3.0 conflicts with your proprietary or SaaS distribution model—treat this as a gate, not a footnote.
  • You expect high write volume or very large tables; row count scales as records × locales.
  • You need ecosystem maturity: this package has 0 stars, 0 dependents, and a single-agency maintainer—vendor and bus-factor risk are material.
  • You need guaranteed fallback behavior; the package provides none, so it becomes your team’s responsibility.

How to Pitch It (Stakeholders)

For executives: “This package is a low-lift way to add multilingual content to our Laravel app without building a custom translation subsystem. It can shorten time-to-market for localized product pages, CMS content, or documentation by reusing Laravel’s ORM and schema tooling. The trade-offs are real: it is AGPL-3.0 licensed, has essentially no community adoption, and provides no editorial workflow, translation history, or fallback logic. I recommend treating it as a time-boxed pilot candidate, contingent on legal review and a production-like performance test—not a platform commitment. If the pilot succeeds, we get international expansion with less custom code and lower initial cost; if not, we avoid over-investing in a niche dependency.”

For engineering: “This is a lightweight Eloquent trait: a translatable() migration macro adds locale and locale_parent_id, and the trait adds translate(), getTranslation(), translations, translationsWithDeleted, and withLocale(). We can whitelist locales and rename columns via translatableConfig(), and transform attributes before saving via translateAttributes(). Key caveats: because all locales live in one table, an unscoped query returns duplicate content—we must enforce locale scoping in a base repository or global scope; fallback behavior, soft-delete lifecycle, and orphan cleanup are ours to build; and we must index locale and locale_parent_id. Given the low adoption and single-maintainer risk, start with one model, measure query performance, and get AGPL compliance signed off before shipping.”