Localization Core Api Laravel Package

Technical Evaluation

Architecture fit

localization-core-api positions itself as a presentation adapter — the HTTP/API edge over a localization domain core. Architecturally that is a healthy pattern (ports-and-adapters): the adapter owns routing, request validation, serialization, and versioning; the sibling localization-core package owns the translation store, locale negotiation, and fallback logic. For a team already running a modular Laravel monolith (nwidart-style modules, or a hand-rolled packages/ workspace), a thin adapter is a low-blast-radius addition: it can be mounted behind a feature flag, versioned independently (/api/v1/locales), and removed without touching domain code.

The caveat is that an adapter has near-zero standalone value. Its behavior — and therefore its technical merit — is entirely inherited from packages in the same liberusoftware namespace, which share the same zero-star, zero-dependent profile. Adopting the adapter means adopting the whole dependency chain, including any transitive Laravel-version pins the core enforces. Treat the unit of evaluation as the suite, not this repository.

Integration feasibility

Mechanically trivial: composer require, Laravel package auto-discovery or a manual ServiceProvider registration, php artisan vendor:publish for config and route files, then a route-prefix/middleware decision. A competent Laravel engineer can have it responding locally in under an hour. That is the full extent of the good news.

Feasibility confidence is low because the artifacts a TPM needs to de-risk an integration are absent: no README-level contract, no published API schema (OpenAPI/JSON:API), no documented locale-resolution semantics, no visible CI badge or coverage signal, no changelog discipline. You cannot write an integration test plan against an undocumented contract, so the true cost is archaeology, not installation.

Technical risk

A composite score of ~19.8 with opportunity at ~45 reads correctly: real gap in the market (Laravel lacks a first-class, API-first localization surface), immature artifact. Opportunity without maturity is a build-vs-buy signal, not an adoption signal.

Key questions (to answer before any commitment)

1. What is the literal text of the LICENSE file, and has legal confirmed derivative-work and redistribution rights?
2. Which exact versions of laravel/framework, php, and liberusoftware/localization-core does composer.json require — and is the constraint a caret or an exact pin?
3. Why is the latest release dated in the future? Is there a tag/changelog mismatch?
4. Is there a CI pipeline, and does it run tests on a matrix of supported Laravel versions?
5. Is there a published request/response schema, or must the contract be reverse-engineered from route and controller source?
6. What are the locale-negotiation semantics — Accept-Language parsing, header precedence, per-tenant override, fallback chain order?
7. Where does the translation store live (database, flat files, external service), and who owns its migrations?
8. Does the adapter assume a specific cache driver, queue, or multi-tenancy package?
9. What is the maintenance commitment from the maintainer — is there a stated support window?
10. Is the core package usable headlessly, letting us swap this adapter for our own controllers?

Integration Approach

Stack fit

Assume Laravel 10/11/12 on PHP 8.1+, Composer 2, and either standard app/ layout or a module loader. Fit is conditional:

• Greenfield API-first service — good fit. Thin, disposable, and you control both sides of the contract.
• Existing Laravel app with lang/ files — moderate fit. You gain an API surface but inherit an opinionated resolution model that may not match your current __() behavior.
• Multi-tenant SaaS with per-tenant locale overrides — unproven fit. Verify tenant scoping explicitly; adapters frequently resolve locale from request context only.

Migration path

Do not rip out an existing localization stack. Instead, insert an anti-corruption layer:

1. Define your own LocaleResolver / TranslationRepository interfaces in application code.
2. Implement them by delegating to this adapter (or directly to localization-core).
3. Migrate one non-critical consumer (e.g., a public marketing endpoint) first.
4. Only after the contract proves stable, point internal call sites at the adapter-backed implementation.

If you are currently on mcamara/laravel-localization (URL-prefix routing) or spatie/laravel-translatable (model attribute translation), recognize these solve different problems. This package is an API surface, not a routing or Eloquent concern; a like-for-like migration does not exist, so scope the work as additive rather than replacement.

Compatibility

• Pin an exact version in composer.json ("x.y.z", not "^x.y"). Future-dated releases make semver untrustworthy; caret ranges will silently pull breaking changes.
• Check route registration for collisions with your existing /api prefix and global middleware stack (auth, throttle, CORS). Adapters commonly assume api middleware group membership.
• Confirm the package's config keys do not collide with your own config/localization.php.
• Verify PHP extension and cache-driver assumptions (Redis vs. file vs. database cache behave differently under locale-key fan-out).
• Test on your actual Laravel minor version — package CI, if any, likely covers only the latest.

Sequencing

Budget for a fork from day one. Given zero dependents, you are almost certainly the first production consumer, and the fork is the realistic steady state.

Operational Impact

Maintenance

The dominant ongoing cost is ownership transfer: expect to vendor or fork within 6–12 months. Practical mitigations:

• Pin exact versions; add a Dependabot/Renovate entry but do not auto-merge — review every diff manually.
• Keep the fork as a thin patch set (≤200 lines) so rebasing stays cheap.
• Mirror the repository internally (GitHub archive or a private remote) so an upstream deletion is not an outage.
• Add a scheduled quarterly review of upstream activity; if commits stop for two quarters, formally transition to "internally maintained."

Support

There is no vendor, no SLA, and no community to escalate to. Support is entirely internal. Realistically you need one engineer who has read the source end-to-end and can be the named owner. That person is a single point of failure — document the contract they hold in a runbook, not in their head.

Scaling

Localization reads are overwhelmingly read-heavy and highly cacheable, which is favorable. Watch for:

• Per-request locale resolution doing work on every call — memoize per request, cache per locale+namespace.
• Cache key cardinality — locale × namespace × tenant can explode; namespace your keys and set explicit TTLs.
• N+1 on translation lookups — if the adapter resolves keys one at a time in a loop, batch at the core layer or preload.
• Cold-start stampede after deploy or cache flush — add jittered TTLs and a warm-up job for the top locales.
• Egress cost if responses are per-locale and uncacheable — front with a CDN keyed on Accept-Language + Vary.

If the core hits a database per request, that is the scaling ceiling; verify before pilot.

Failure modes

Ramp-up

Code volume is likely small, so reading it is fast — a day or two. The expensive part is the absence of documentation: engineers must infer the API contract from controllers and tests, and every inference is a potential production bug. Expect 3–5 engineer-days to first confident contribution, versus roughly half a day for a well-documented equivalent (e.g., a spatie package).

Onboarding artifacts you must create yourself, and should treat as deliverables of Phase 1–3:

1. An internally written docs/localization-api.md capturing the request/response contract.
2. A Postman/.http collection or OpenAPI stub for the endpoints.
3. Contract tests in your own repo that fail loudly if upstream behavior shifts.
4. A one-page runbook: owner, pin policy, fork procedure, rollback.

TPM recommendation: Do not adopt on the strength of this package alone. Its opportunity signal is genuine — Laravel has no dominant API-first localization surface — but a NOASSERTION license plus zero dependents plus anomalous release metadata is a stop-the-line combination. Sequence as: legal clearance → source audit → isolated spike behind an anti-corruption wrapper → pilot. If legal does not clear it in Phase 0, treat the 45-point opportunity score as a build argument rather than a buy argument, and scope a 4–6 week internal adapter over your existing translation store instead.