Localization Laravel Package

Technical Evaluation

Basis of assessment: Derived solely from the v1.0.0 release notes. No source review, documentation audit, or dependency analysis has been performed; all findings below are hypotheses to be validated in a spike.

Architecture fit: atannex/localization is positioned as a localization platform rather than a helper library — a locale registry, negotiation middleware, routing layer, Eloquent trait, formatting layer, queue hook, CLI tooling, and a Filament panel plugin in one package. That breadth is attractive for a greenfield Laravel 11/12 application but represents significant surface area for a first release. Two overlap points need resolution before adoption: (1) it sits alongside Laravel's native translator (__(), lang/ files, pluralization) and it is unclear whether it wraps, replaces, or defers to it; (2) the translatable-attribute trait competes directly with spatie/laravel-translatable, so any existing model layer must be assessed for coexistence or migration cost. The "driver-aware JSON scopes" claim implies per-driver query strategies (MySQL/Postgres/SQLite JSON operators), which is a meaningful differentiator but also the highest-risk code path for correctness and index usage.

Integration feasibility: High for the request-side features (registry, negotiation, switcher, hreflang) which are additive and config-driven. Medium for routing, since locale-prefixed URLs will collide with existing route definitions, route caching, and any legacy URL structure requiring redirects. Low-to-medium for translatable attributes, as this implies schema changes (JSON columns or side tables), a content backfill, and a rewrite of read/write paths across every localized model. The Filament plugin is a bounded, opt-in surface and can be deferred. Overall the package is adoptable incrementally, which materially lowers the risk of a first-release dependency.

Technical risk:

• Maturity. v1.0.0 by a single-author vendor (bus factor 1). No track record, no LTS, no evidence of a support policy. Treat as a pinned, forkable dependency.
• Negotiation precedence. Eight concurrent signals (URL prefix, domain, query, user, session, cookie, Accept-Language, geo) create a large configuration matrix. Wrong precedence yields wrong-language content — an SEO, accessibility, and in some jurisdictions a legal/compliance exposure.
• Geo detection. Implies an external IP-to-locale source (MaxMind-class database or API). Introduces a privacy/GDPR review item, a runtime dependency, and a per-request latency/caching concern.
• Cache interaction. Session- and cookie-derived locale conflicts with shared HTTP caches and CDNs unless Vary and cache-key strategy are handled explicitly. This is a common production failure mode.
• SEO surface. Localized URLs plus hreflang are unforgiving: incorrect hreflang reciprocity, missing x-default, or unstable locale resolution can degrade indexing.
• JSON scopes. Query behaviour and index utilization vary by driver; MySQL functional indexes may be required for acceptable performance at scale.

Key questions for the maintainer / spike:

1. Does the package replace Laravel's translator or layer on top of it? What is the fallback chain per locale and per key?
2. What is the default negotiation strategy order, and is it overridable per route group?
3. Which geo provider(s) are supported, is the lookup local or remote, and what is the documented data-retention posture?
4. What is the migration path from spatie/laravel-translatable or from hand-rolled JSON columns? Is there a backfill command?
5. Are config, migrations, and translations publishable? Is there a documented upgrade/BC policy pre-2.0?
6. Which Filament major version(s) does the plugin target?
7. Test coverage, CI matrix across PHP 8.2–8.4 and Laravel 11/12, and static analysis level?
8. License, security disclosure process, and expected release cadence?

Integration Approach

Stack fit: Explicitly targets PHP 8.2+ and Laravel 11/12, which matches a modern application baseline. No legacy-version support means it is unsuitable for a codebase still straddling Laravel 10, and it hard-couples the localization upgrade to the framework upgrade.

Migration path: Adopt in layers, each independently revertible.

1. Publish config and registry; do not alter routing or models. Validate the ~110-locale catalog against the actual supported language set (110 is almost certainly more than the business needs, and every enabled locale is a translation and QA obligation).
2. Enable negotiation in observe-only mode — resolve and log the negotiated locale without redirecting — to measure precedence behaviour against real traffic.
3. Introduce localized URLs and the switcher together with a 301 redirect map for legacy URLs, then regenerate sitemaps with hreflang.
4. Roll the translatable-attribute trait out one model at a time, starting with the lowest-traffic, lowest-cardinality model, with a backfill and a rollback script per model.
5. Add Filament tooling last, for content operators rather than engineers.

Compatibility: Principal conflicts are route caching, existing route definitions, any current lang/ directory conventions, and a pre-existing translatable implementation. Verify route:cache and config:cache under localized routing before committing. Confirm that the missing-key tracker and coverage commands do not run in production request paths.

Sequencing: Proof-of-concept branch (2–5 days) → config/registry + negotiation logging → routing, switcher, hreflang, redirects → model trait on one model, then breadth → queue propagation and locale-aware formatting → Filament plugin → coverage/export/import wired into CI as a gate. Do not parallelize the routing and model-trait phases; they have independent rollback stories and conflating them complicates incident diagnosis.

Operational Impact

Maintenance: Low code footprint for the team, but the package itself becomes load-bearing infrastructure owned by a third party. Pin an exact version, mirror the repository, and budget periodic review of upstream releases. Expect breaking changes before 2.0 and plan the upgrade cadence accordingly.

Support: No commercial support indicated. Internal ownership must be assigned — realistically one backend engineer — with the ability to patch or fork. Documentation quality is unverified and is a gating item for the proof of concept.

Scaling: Negotiation adds per-request work; geo lookups must be cached locally (in-process or Redis) with a hard timeout and a safe default. Localized routing multiplies route count and route-cache size. JSON-scoped translated attributes require index review per driver and per query pattern; watch for full-table scans on locale-filtered reads as content volume grows. Export/import and coverage commands should be scheduled off-peak, not run interactively against production.

Failure modes to design against:

• Mis-negotiated locale serving wrong-language content (detect via negotiation logging and a canary locale).
• Geo provider outage or timeout — must degrade to Accept-Language, never to an error.
• Cookie/session locale poisoning shared caches — explicit Vary and cache-key policy.
• Missing translations surfacing raw keys in production — enforce the coverage command as a CI gate.
• Queue workers leaking locale between jobs — verify the propagation hook under retries and batched chains.
• Driver-specific JSON scope regressions after a database upgrade — include in the regression suite.
• Filament plugin breakage on a Filament upgrade — treat as a coupled dependency pair.

Ramp-up: Backend engineers already fluent in Laravel localization need roughly half a day to learn the registry and negotiation model, plus one to two days for the translatable-attribute semantics. Content operations need a documented export/import and coverage-review workflow. QA needs a locale matrix (at minimum: default, one RTL, one long-string, one fallback-only locale) added to the regression checklist. Total organizational ramp-up is modest; the real cost is the ongoing translation and QA obligation that enabling additional locales creates.