Localization Core Api Laravel Package

Getting Started

This is a presentation adapter, not a full localization engine. It sits between a localization core domain package and your HTTP/JSON layer, so the first thing to establish is what it depends on and what it exposes.

1. Install the adapter together with its core. A bare composer require liberusoftware/localization-core-api will likely fail at runtime if the localization core contracts it adapts are not present. Inspect composer.json require/suggest blocks before installing and add the core package in the same step.
2. Confirm the service provider registers. Check extra.laravel.providers for auto-discovery. If absent, add the provider manually in bootstrap/providers.php (Laravel 11+) or config/app.php. Nothing else in the package will work until routes and bindings are loaded.
3. Read src/Http/ and src/Routes/ first. As a presentation adapter, the useful surface is almost always: route definitions, controllers, API Resources/transformers, and request validators. Those files tell you more about day-to-day behaviour than any README.
4. Publish config if a config stub exists: php artisan vendor:publish --tag=localization-core-api-config. Look for route prefix, middleware stack, and any enabled flag.
5. Verify the wiring before writing code: php artisan route:list --path=api and php artisan about. If no localization routes appear, the provider is not loaded or the module is gated behind a config switch.

First use case: exposing the locale catalogue to a frontend. Boot the API, GET the locales/translations endpoints, and point an Inertia page or SPA service at them instead of hard-coding locale lists in JavaScript. That is the smallest path from install to value, and it validates the whole adapter chain (provider → routes → core binding → resource transform) in one request.

Implementation Patterns

Treat it as an edge layer, not a domain layer. Business rules about which locales are enabled, fallback chains, or translation completeness belong in the localization core. Your code here should be limited to transport concerns: serialization shape, pagination, auth scoping, cache headers. If you find yourself writing locale-resolution logic in a controller, it belongs upstream.

Consume through the JSON contract, not the classes. Resolve the adapter's endpoints over HTTP from your SPA/mobile client, and in server-side code prefer the underlying core service over the adapter's controllers. Controllers are for external callers; internal callers should not re-enter their own HTTP stack.

Override resources rather than forking. The most common real-world need is changing the payload shape ({ code, name, native_name, active } → something flatter for your frontend). Bind your own JsonResource or DTO via the container and point the package config at it, if the package exposes such a hook. If it does not, subclass the resource and swap the binding in a small local service provider — keep the vendor directory clean so upgrades stay cheap.

Middleware for locale negotiation. Wrap the package's route group with a SetLocale middleware that reads Accept-Language, a ?locale= query param, or a tenant column, then calls App::setLocale(). This is the adapter's natural integration point and keeps the negotiation policy visible in one place rather than scattered across controllers.

Cache the catalogue aggressively. Locale lists and translation payloads change rarely and are read constantly. Cache the serialized response (tagged by locale) for minutes-to-hours, and flush on translation writes. This is usually the single biggest performance win when exposing localization over HTTP.

Multi-tenant scoping. If tenants have their own locale sets, do not create parallel route files — add a tenant-resolution middleware ahead of the package routes and let the core filter by tenant. Verify the adapter respects the resolved tenant rather than reading global config directly.

Feature-flag the module. Given the adoption profile, gate the routes behind a config/env flag so you can disable the adapter in a deploy without removing the dependency.

Gotchas and Tips

Zero stars, zero dependents, NOASSERTION license. This is the dominant risk, not a footnote. NOASSERTION means the repository does not declare a recognized OSI license; it does not mean "permissive." Get written clarification from the maintainer before shipping it in a commercial product, and check whether the surrounding Liberu modules are under a compatible license.

The release date is ahead of the current date. Treat the 2026-10-26 tag as metadata you cannot trust for stability signalling. Pin to a specific commit SHA in composer.json rather than a floating constraint, and diff the tag against main before trusting it.

Auto-discovery silently half-works. If routes load but bindings do not resolve, you will get container exceptions that look like core-package failures. Register the provider explicitly rather than relying on discovery, and confirm with php artisan about that the module is listed.

Route collisions on /api/.... Presentation adapters frequently assume a clean api prefix. If you already own /api/locales, the package's routes may shadow or be shadowed by yours — route registration order matters. Set a distinct prefix in config (e.g. api/localization) to eliminate the class of bug entirely.

Config caching traps. After changing package config, run php artisan config:clear. A stale cached config is the most common cause of "the provider is ignored my setting" reports with adapters like this.

Cache invalidation on translation writes. If you cache responses and translations are edited through a different module, invalidation will not be automatic. Wire an event listener (or a scheduled flush) to the core's translation-updated event; otherwise editors will report changes "not saving" when they are simply cached.

Versioning is your responsibility. The adapter has no published upgrade history to learn from. Wrap its endpoints in your own thin controller or client service so a breaking change in the adapter is a one-file fix rather than a scattered edit.

Debugging checklist, in order: (1) php artisan route:list — do the routes exist at all? (2) php artisan about — is the provider loaded? (3) resolve the core contract from the container in tinker — does it bind? (4) hit the endpoint with Accept: application/json so exceptions render as JSON instead of an HTML error page. Most failures in this kind of adapter are at step 2 or 3, not in the controller logic.

Best extension point to bet on: the container bindings, not the config file. Config keys in low-traffic packages are often undocumented and unstable; swapping a binding in your own service provider is a pattern the Laravel ecosystem guarantees. Fallback plan: if the adapter proves unmaintained, its controllers are typically thin enough to reimplement against the core package in an afternoon — keep that option open by never letting the adapter's DTOs leak into your domain code.