Doctrine Translatable Bundle Laravel Package

Product Decisions This Supports

• Localization architecture (build vs. buy). Decides whether the team builds its own per-locale content persistence layer or adopts an existing Doctrine extension. This package is the persistence half of i18n — it stores field-level translations as side-table records rather than duplicating whole entities or stuffing JSON into a column.
• Roadmap sequencing for market expansion. Going multi-locale is usually gated on schema, editorial workflow, and search — not on the front-end language switcher. This package unblocks the schema gate cheaply, which lets you sequence "second market launch" earlier without a data-model rewrite.
• Content model standardization. Use cases: CMS-style pages, product catalogs, category/attribute names, legal and marketing copy stored in the database, any entity whose fields change per market. It pushes the org toward a single, consistent translation convention instead of three teams inventing three.
• Editorial and admin tooling decisions. Because translations are addressable records rather than opaque blobs, you can support partial translations, per-locale review status, and fallback-to-default-locale behavior — which is what actually determines whether a content team can ship without engineering.
• Data portability and exit cost. Choosing side-table translations (this package's model) over JSON columns is a decision about query-ability, indexing, and future migration effort. It is reversible, but only if you choose it deliberately now.
• Ecosystem risk budgeting. Adopting a low-adoption dependency is a resourcing decision as much as a technical one: someone must own it.

Important scoping note: despite being a PHP package, this is a Symfony bundle for Doctrine ORM — not a Laravel package. If the codebase in question is Laravel/Eloquent, this does not apply and the real decision is a Laravel-native translation package (e.g., spatie/laravel-translatable) or a hand-rolled side table. Confirm the stack before taking this to a build-vs-buy review.

When to Consider This Package

Consider it when all of these hold:

• The application is Symfony with Doctrine ORM, and content lives in entities rather than in a headless CMS.
• You need field-level translations (name, description, slug per locale) rather than whole-entity duplication.
• You want the convention and entity wiring for free (annotations/attributes, fallback locale, repository hydration) instead of designing the schema and hydration yourself.
• The team is willing to vendor, pin, or fork the dependency and assign a named owner.
• The scope is one or two entities in a pilot, not every table on day one.

Look elsewhere when any of these hold:

• The stack is Laravel or plain PHP. This bundle is Symfony DI + Doctrine-specific; forcing it is pure friction.
• You need active maintenance, security responsiveness, or vendor support. At ~14 stars and zero dependents, there is effectively no community to catch regressions and no bus factor. Treat it as source code you are adopting, not a maintained product.
• Localized search, sorting, or full-text is a requirement. Side-table joins make ranked, locale-aware search expensive; PostgreSQL jsonb with generated columns or a search engine may serve you better.
• High write throughput or very wide entities. Every translated field becomes a join; measure before committing, and don't adopt it for analytics-shaped tables.
• You need the full editorial workflow (translation memory, review states, provider integrations). That's a TMS or a CMS feature, not a bundle feature.
• Strong alternatives fit better: Gedmo/DoctrineExtensions Translatable (far larger install base), KnpLabs DoctrineBehaviors, Sylius-style translation models if e-commerce, or a ~1–2 week hand-rolled entity_translation side table — which is genuinely competitive here given the adoption gap.

Adoption gate: run a one-week spike on a single entity. Exit criteria: does it cover fallback locale + partial translations, does hydration stay within your query budget, and can you upgrade the dependency without touching application code? If any answer is "no," build the side table yourself and keep the dependency risk at zero.

How to Pitch It (Stakeholders)

For executives (one paragraph):

To sell into additional markets, we need to store the same content in multiple languages. Today that means either a custom database layer we build and maintain, or a third-party dependency. This package is a small, MIT-licensed, free library that supplies the database pattern for translated content and connects it to our framework. It is not a platform commitment: it's a schema convention plus a thin integration layer. Estimated build avoided: roughly 1–2 weeks of engineering plus ongoing schema maintenance. The risk is maintenance, not licensing or lock-in — adoption is low (about 14 GitHub stars, no downstream dependents), so we would pin a known-good version, vendor the source into our repository, and assign one engineer as owner. If it disappoints, the translations live in ordinary database tables we control, so switching costs are a migration script, not a rewrite. Recommendation: approve a one-week spike on a single entity, with a go/no-go review, rather than a broad rollout.

For engineering leads:

• What it is: the Symfony integration layer for prezent/doctrine-translatable — entity mapping, listener wiring, locale/fallback configuration, and repository hydration. The translation logic itself is in the underlying library.
• What we get for free: the side-table schema convention, per-locale field resolution with fallback, and the join/hydration code we'd otherwise write and debug.
• What we own: version pinning, a vendored copy or fork, upgrade testing, and query-plan review. Assume no upstream support; budget a small recurring maintenance line, not zero.
• What we must validate in the spike: N+1 behavior on list endpoints, indexing strategy on (locale, field, foreign_key), behavior for partially translated records, and whether our admin forms and serializers can consume the resolved values cleanly.
• Where it doesn't fit: any Laravel service, any table needing locale-aware search or analytics, and any workflow requiring translation review states — those need a TMS or CMS, not a persistence bundle.
• Fallback plan: if the spike fails, a hand-rolled entity_translation table with a resolver service is roughly the same effort and carries no dependency risk. Decide on evidence, not on the package's convenience.

The ask: one engineer, one week, one entity, explicit exit criteria, and a written go/no-go. Low cost, fully reversible, and it settles the localization schema question before it blocks a market launch.