Localization Core Laravel Package

Technical Evaluation

Architecture fit. localization-core is scoped as a Liberu module, not a general-purpose i18n library. The name (module-localization-core) and the "for Liberu applications" framing signal a service-provider package that assumes Liberu's module conventions, config layout, and likely its own user/tenant model. Inside a Liberu-based application it should drop in cleanly; outside that ecosystem, expect to spend time reverse-engineering implicit assumptions. The functional scope is unusually broad for one package — locale resolution (negotiation), preferences (persistence), propagation (request/job/response context), and UI direction (LTR/RTL) are four separable concerns bundled together, which means partial adoption may be difficult. If we only need resolution + preferences, we may end up carrying the whole bundle.

Integration feasibility. MIT license removes legal friction, and Composer installation into a Laravel app is a known quantity. The real cost is discoverability: with 0 stars and 0 dependents, we are the first external integrator. There is no corpus of Stack Overflow answers, no third-party tutorials, and no community to sanity-check behavior against. Integration effort therefore depends almost entirely on whether the repository ships README usage examples, published config, and a service-provider contract we can read. Budget a source-reading spike before committing to an estimate.

Technical risk.

• Bus factor of one. No dependents, no stars, no downstream usage to surface regressions. A single abandoned maintainer leaves us owning the code.
• No ecosystem pressure. Zero dependents means the public API has never been stressed by an outside consumer; breaking changes can ship without anyone noticing.
• Release cadence ambiguity. A single recent release with no visible track record makes semver discipline unknowable. Treat the current version as pre-stable regardless of what the tag says.
• Overlap with mature incumbents. Laravel's native App::setLocale/Lang, plus established packages for route-based localization and Accept-Language negotiation, cover part of this ground. Adopting this package means accepting a narrower maintenance pool than the alternatives.
• RTL propagation is the highest-risk surface. UI direction leaks into Blade/Vue/React rendering, CSS logical properties, and email templates. Bugs here are visible to end users and awkward to roll back.
• Cross-context propagation is easy to get wrong. Locale must survive queue jobs, scheduled commands, API responses, mailables, and notifications. A package that captures locale at request time can silently reset to default in a worker.

Key questions.

1. Which Laravel and PHP versions are supported, and is there a CI matrix proving it?
2. Does it integrate with Laravel's native locale primitives, or does it maintain a parallel locale state?
3. Does it ship the user_locale/preferences schema, and does that schema assume a specific user or tenant model?
4. How does locale propagate into queued jobs, scheduled tasks, and outbound mail — middleware, context, or explicit API calls?
5. Does it implement Accept-Language negotiation and fallback chains, or delegate to an existing package?
6. What is the test coverage, and is there a documented upgrade path or changelog?
7. Does it conflict with, or duplicate, an existing localization package already in our stack?
8. Who maintains it, and what is the commitment to security patches?

Read on the scores. The overall score of ~19.9 against an opportunity score of ~43.5 is the tell: the problem is high-value and recurring (i18n and RTL are perennial roadmap items), but the artifact has no traction. That combination argues for a time-boxed pilot, not a platform decision.

Integration Approach

Stack fit. Assume Laravel 10–12 on PHP 8.2+ until verified against composer.json. The package should be additive — a service provider, publishable config, and probably middleware. Verify it does not hijack the framework's locale handling in a way that breaks existing __() calls; if it does, isolate it behind our own thin façade.

Migration path. Do not call the package directly from controllers, models, or Blade. Wrap it in an internal LocaleService (or a small adapter interface) that exposes only the operations we need: resolveForRequest(), preferenceFor(User), setPreference(), direction(). That façade costs an afternoon and buys us a swap path to Laravel-native primitives or an established package if the dependency stalls. If the package owns migrations, run them in a dedicated migration and keep our own preference columns or tables where feasible so we are not locked into its schema.

Compatibility checks before writing code.

• Run composer why-not against our current framework pin.
• Grep our codebase for existing locale middleware, setLocale calls, and translation packages to map collisions.
• Confirm the package does not register a global middleware that assumes it is the sole owner of locale.
• Verify behavior under Octane and under queue workers — those are the environments where locale state leaks.

Sequencing.

1. Spike (2–3 days). Install in a scratch branch, read the service provider and contracts, exercise resolution in a request, a queued job, and a mailable. Record actual behavior against the key questions above.
2. Façade. Build the adapter and route the pilot surface through it. No direct imports elsewhere.
3. Pilot scope. One application, one non-critical locale pair, one LTR/RTL contrast if RTL is in scope. Feature-flag the locale source so we can fall back to framework defaults instantly.
4. Instrument. Log resolved locale, source (user preference vs. header vs. default), and direction per request. This is the only way to debug propagation failures in production.
5. Expand. Add locales and surfaces only after the propagation path through queues and mail is proven.
6. Contingency. If the spike fails the key questions, fall back to Laravel native plus a small amount of our own negotiation code — that is a smaller total effort than adopting an unproven dependency we cannot debug.

Operational Impact

Maintenance. Treat this as a vendored dependency. Plan for the realistic case that upstream goes quiet: fork to an internal namespace on first adoption, or at minimum mirror the repository and pin the exact version with a lockfile. Assign a named owner. Review the diff before any version bump; with zero dependents, a patch release is not a signal of safety.

Support. There is no community to escalate to. Internal engineers will be the support tier, which means onboarding documentation is our responsibility, not the maintainer's. Write a one-page internal runbook covering how locale is resolved, where preferences are stored, and how to force a locale for debugging.

Scaling.

• Locale resolution typically runs on every request. If it queries preferences from the database, ensure that lookup is cached per user (request-scoped or short-TTL) or it becomes a per-request query tax on every page.
• Fallback chains can multiply lookups when a translation is missing in the active locale. Watch for N+1 patterns in translation resolution under load.
• Long-running workers (Octane, Horizon) must reset or explicitly set locale per job; stale locale state in a reused worker is a classic production incident.
• RTL support has negligible runtime cost but real frontend build implications — CSS logical properties, icon mirroring, and component-level review.

Failure modes to plan for.

• Silent fallback. A malformed or unexpected locale resolves to the default with no error; users see English and nobody alerts. Mitigate with instrumentation and a validation guard.
• Queue drift. Jobs execute under the worker's locale rather than the dispatching user's. Highest-likelihood production bug; test explicitly.
• Cache poisoning. Locale-keyed caches (translation caches, rendered fragments) served to the wrong locale. Ensure locale is part of the cache key, or disable shared caching for localized fragments.
• RTL regressions. Layout breakage that only surfaces with real content in a real language. Requires native-speaker QA, not just engineer review.
• Upstream breakage on upgrade. No downstream consumers means no early warning. Pin, test, then bump.
• Abandonment. No security patching. Monitor for CVEs in transitive dependencies and be prepared to maintain the fork.

Ramp-up. Low for a Laravel developer reading the source — the domain is familiar and the surface is small. Budget roughly one engineer-week for the first developer to become genuinely confident, most of it spent on propagation semantics rather than the API. Frontend contributors need separate ramp-up for RTL conventions, and QA needs a test matrix per locale and direction. Do not assume the package's UI-direction handling removes frontend work; it flags direction, it does not mirror your CSS.

Bottom line. Viable as a time-boxed pilot inside a Liberu-aligned application, behind an internal façade, with a named owner and a pinned version. Not viable as the strategic foundation for multi-locale, multi-tenant localization without a fork-and-own decision and a documented exit path to Laravel-native primitives. The opportunity score is high because localization is genuinely underserved in our roadmap; the package score is low because this specific artifact is unproven. Fund the spike, not the commitment.