Nova Translatable Laravel Package

Technical Evaluation

Architecture fit. This is a Laravel/PHP package for managing translated model fields, with a notion of a "main language" and per-locale field storage. For a TPM, that means it sits on the Eloquent write path — not at the edge of the stack. Any defect here is a content-integrity defect, not a UI defect. The 0.2.3 fix ("saving empty fields for main language") confirms the package owns read and write semantics for translatable attributes, including how empty values are persisted for the primary locale. That is core behavior for any editorial workflow.

Integration feasibility. Mechanically low-friction: standard Composer install, service provider registration, likely config/migration publishing, and a trait or cast applied to existing models. The friction is procedural, not technical — 0.2.3 is a pre-1.0 patch, so no API stability guarantee exists. We should assume the trait signatures, config keys, and storage shape may still move before 1.0.

Technical risk.

• Data integrity (high). The just-fixed bug is a save-path bug that would silently drop content for the primary language — i.e., users clear a field or submit an empty value and the old value silently persists, or an empty value fails to persist at all. Either direction produces content that diverges from what an editor saw on screen. Bug fixed, but bugs of this class cluster: expect similar edge cases in fallback-locale handling, null vs. empty-string, and partial-form submissions.
• Maturity (medium-high). Pre-1.0 with a single patch-level release history. No evidence yet of a deprecation policy or LTS posture.
• Support surface (medium). Unknown maintainer count and responsiveness; unknown Laravel/PHP version matrix.
• Storage coupling (medium). If translations are stored as JSON columns, querying and indexing translated content is constrained; if stored per-locale in side tables, joins and eager-loading strategy become an architectural decision we inherit.

Key questions.

1. Which Laravel and PHP versions are supported and tested in CI?
2. Does the fix in 0.2.3 change the persisted representation of empty values (null vs. ''), and does that require a data backfill or read-side compatibility shim for content saved on 0.2.0–0.2.2?
3. Is the main-language value stored in the base table column or duplicated into the translation store? This determines whether the bug could have caused divergence between the two.
4. What is the storage strategy (JSON column vs. translation table), and how does it behave under where() / sorting on translated fields?
5. Who maintains it, what is the release cadence, and is there a stated 1.0 timeline?

Integration Approach

Stack fit. Native Laravel idiom — provider + trait/cast + published config and migrations is exactly how we would build this in-house. That makes it cheap to adopt but also cheap to replace, which is the right risk posture for a pre-1.0 dependency on the write path. It fits conventional Eloquent CRUD and admin-panel patterns; it is a poor fit if we need translated full-text search, per-locale sorting at the database level, or heavy reporting over translated content.

Migration path. Two distinct migrations, and they should not be conflated:

1. Schema — publish and run the package migrations, then add translatable columns/tables to each model we localize. Start with a single low-risk model.
2. Content — backfill existing single-language data into the package's "main language" slot, and verify it lands where the package expects to read it. Given that 0.2.3 fixed main-language empty-field saving, the backfill must be validated field-by-field against a known-good export, not just row counts.

Compatibility. Pin the exact version (0.2.3, not ^0.2) in composer.json for the pilot. Confirm the CI matrix covers our runtime before adopting. Run our own acceptance tests for the semantics the release note touches — empty string, null, whitespace-only, and field-cleared-then-saved — because that is precisely where the package just proved fallible.

Sequencing.

1. Spike: install 0.2.3 in a scratch branch, apply to one internal model, write the empty/null/main-language regression tests first.
2. Staging: publish migrations, backfill one model's content, diff the rendered output locale-by-locale against current production.
3. Production pilot: one model, one locale pair, with a rollback plan that includes a schema and content revert.
4. Expand model-by-model only after the pilot survives a full editorial cycle (create, edit, clear a field, save, re-read in both locales).
5. Re-evaluate adoption breadth and upgrade cadence once 1.0 ships.

Operational Impact

Maintenance. Low ongoing code maintenance, non-trivial version-watch overhead. Pre-1.0 means minor bumps (0.3, 0.4) can carry breaking changes; budget a recurring review of each release note and pin deliberately. Any release touching the save path should be treated as a mandatory review, not an auto-merge — 0.2.3 is the template.

Support. Upstream support is unproven. Mitigate by (a) vendoring or forking readiness — the surface area is small enough that a fork is realistic, (b) keeping our translatable-field access behind a thin internal abstraction so the package is not sprayed across the codebase, and (c) capturing our own regression suite for the write path so we can validate any upgrade without depending on upstream tests.

Scaling. Watch for N+1 queries when listing models with translated fields — eager-loading must be configured explicitly per model. If translations land in JSON columns, filtering and sorting translated content will not scale past small tables; plan to keep translated-field queries to primary-key and base-column predicates. Read-heavy public pages should sit behind a cache keyed by locale + entity, invalidated on save.

Failure modes.

• Silent content divergence (highest severity): an editor clears a main-language field, the value does not persist as expected, and the stale value serves to users. 0.2.3 addresses this specific case but establishes that the class exists.
• Locale fallback gaps: a missing translation returns null or the wrong locale where templates expect a string — surfaces as blank UI, not an error.
• Partial-form saves over a mixed translatable model: one locale's payload overwrites another's, or unchanged fields are nulled out.
• Migration reversibility: published migrations that drop or reshape translation storage on rollback; verify down() before running against anything that matters.
• Upgrade breakage: a 0.3 bump changes trait or config signatures during a routine dependency update and fails at runtime, not at install time.

Ramp-up. For a Laravel-fluent team, hours to productivity on the trait/cast API; days to confidence on locale fallback and empty-value semantics. The real ramp-up cost is documentation we cannot yet verify — release notes at this granularity suggest thin docs. Budget for one engineer to own the package relationship, write the regression suite, and be the gate on releases. Editorial stakeholders need a short brief on how empty vs. untranslated values render, since that distinction is user-visible and is exactly what 0.2.3 was fixing.