Entity Translation Bundle Laravel Package

Product Decisions This Supports

• Presentation-layer localization of enum-like values. The bundle targets a recurring, unglamorous problem: classes that behave like enums (status codes, roles, categories, order states) need human-readable, translatable labels everywhere they surface — admin tables, filters, forms, emails, exports, and audit logs. A PM can treat this as a scoped feature ("consistent, translatable labels for domain states") rather than an open-ended i18n initiative.
• Build vs. buy for a "label registry." The alternative is a hand-rolled resolver (a service mapping class + constant to a translation key, plus a Twig helper). Building is ~1–2 days of engineering plus ongoing ownership; adopting is a composer require plus translation catalog work. This is a genuine buy-leaning decision if the team is on Symfony 6.4+ and PHP 8.3+ and already uses the Translation component — but the small surface area means building is a credible fallback.
• Architecture decision: keep display strings out of the domain. Adopting a translation-backed label mechanism reinforces the standard "no pretty names in domain code" rule — enums stay machine-readable, labels live in XLIFF/YAML catalogs. That is a durable decision worth recording regardless of whether this specific bundle is chosen.
• Localization roadmap sequencing. Because labels flow through standard Symfony translation catalogs, this plugs into existing translator/vendor workflows (CAT tools, freelance translators, per-locale review). It makes "add a fourth language" a catalog task rather than a code task — useful when scoping market expansion.
• Per-tenant and per-context terminology. Where different customers or brands call the same state something different ("Cancelled" vs. "Voided"), a translation-key indirection is the cheapest place to absorb that variance. Worth validating whether the bundle supports catalog/domain overrides before promising it.
• Roadmap de-scoping. If adopted, this removes a recurring line item from every feature that introduces a new enum ("and add labels for the new statuses"). That compounding saving is the real ROI case, not the first feature.

When to Consider This Package

Consider it when:

• The stack is Symfony 6.4 or later on PHP 8.3 or later — note this is a Symfony bundle, not a Laravel package, so a Laravel codebase would need a wrapper or an equivalent in-house solution. The 1.0.11 release tightened both constraints (it previously tolerated older Symfony/PHP), so confirm your platform baseline before planning to adopt.
• You have (or expect) many enum-like classes and inconsistent, duplicated label logic across Twig templates and serializers.
• You already use Symfony Translation and want labels to live in the same catalogs and workflows as the rest of your copy.
• The team is comfortable vendoring or forking a small dependency. With 5 stars and 0 dependents, treat it as "small library you may need to own," not "ecosystem-standard component."
• The integration is timeboxable — a spike of 1–2 days should be enough to confirm the API fits your enum representations (class constants vs. PHP 8.1+ backed enums).

Look elsewhere (or build) when:

• The application is Laravel — use backed enums with a label() method backed by lang/*.php files, or an equivalent Laravel-native pattern; porting a Symfony bundle is not worth it for this scope.
• Your platform is on PHP < 8.3 or Symfony < 6.4. This release is a hard break for those versions — there is no backward-compatible lane, so you would be stuck on 1.0.10 or earlier (unmaintained) or need to fork and relax the constraints yourself.
• You need labels editable by non-developers at runtime (admin CRUD over translations, per-tenant overrides in the database). That calls for a translation-entity approach, not catalog files.
• You need maintenance guarantees, security SLAs, or a support contract — near-zero adoption and a small maintainer base mean high bus factor and no community backstop.
• You need heavyweight formatting (ICU plurals, gendered forms, locale-aware number/date embedding) that a thin label mapper may not cover.
• Your label needs are single-locale and stable — a match expression or a label() method is less machinery than a bundle plus translation catalogs.

Due diligence checklist before committing: confirm the actual API surface against your enum style, check the release cadence and open-issue responsiveness, confirm Symfony ≥ 6.4 and PHP ≥ 8.3 support in your environments (CI, prod, and any long-lived branch), and read the source (it is small and MIT-licensed, so a fork is a realistic hedge). Note that 1.0.11 also dropped the unused doctrine/annotations dependency, which is a small but welcome supply-chain cleanup — one fewer transitive package to track.

How to Pitch It (Stakeholders)

To executives (one paragraph): We have a recurring cost every time we add a new status, role, or category — someone has to add pretty, translated names in several places, and they drift. This is a small, MIT-licensed Symfony component that standardizes that: labels live in our normal translation files, so adding a language or renaming a status becomes a copy task instead of an engineering task. Cost is low (a short integration spike), risk is low and bounded (small, permissively licensed code we could fork and own if needed), and the payoff compounds across every future feature that introduces a new state. The latest release (1.0.11) tightened its platform requirements to Symfony 6.4+ and PHP 8.3+ and shed an unused dependency, which is an alignment check for us rather than a blocker if we are already on those versions. Recommendation: fund a timeboxed spike, not a full rollout, and decide on measured results.

To engineering: This is a thin Symfony bundle that resolves translatable labels for enum-like classes through the existing Translator, keeping pretty names out of domain code and out of Twig switch blocks. It reduces duplication and makes label coverage a catalog concern. The 1.0.11 release is a compatibility-tightening release, not a feature release: it drops Symfony < 6.4, drops PHP < 8.3, and removes the unused doctrine/annotations dependency. There are no new APIs or deprecations to migrate around, but the version floor is now a hard gate — confirm every environment we ship to (local, CI, staging, prod, long-lived release branches) meets PHP 8.3 and Symfony 6.4 before pinning. If any target is older, either defer adoption or plan to fork and relax the constraints. Other caveats to weigh honestly: it has negligible public adoption (5 stars, 0 dependents), so we should read the source, pin the version, and be prepared to vendor it. Please validate against our backed enums and current Symfony version, and report back on API fit and any gaps versus a ~100-line in-house service.

Framing the decision: Present it as "adopt a small dependency with a fork fallback" versus "build and own a small service," now with an explicit platform gate (PHP ≥ 8.3, Symfony ≥ 6.4). Set success criteria for the spike — coverage of all existing enum-like classes, no template regressions, translator workflow unchanged, a rough count of duplicated label logic removed, and confirmation that every deployment target meets the new version floor — and make the go/no-go call on those, not on the package's popularity.