Locale List Laravel Package

Technical Evaluation

Architecture fit

• The package is a static data artifact, not a runtime library. It ships lists of locales (code → display name) across many target languages and serialization formats (JSON, PHP array, YAML, CSV, XML). There is no service provider, no facade, no config file, and no public API surface — you read files from vendor/ and decode them.
• This makes it a natural fit for the "leaf" of a Laravel app: a locale picker, a validation rule for locale codes, a normalization layer, or seed data for a locales table. It is not a substitute for a translation/i18n system (it does not translate UI strings).
• Because it is data-only, it composes cleanly with anything: Livewire/Inertia/Blade, API resources, queued jobs, console commands. No container bindings to wire, no boot-order concerns.
• Architectural decision to make up front: direct vendor reads vs. an internal abstraction. We should wrap it in a single LocaleRepository-style class so the package is swappable for symfony/intl or an in-house dataset later without touching call sites.

Integration feasibility

• One composer require umpirsky/locale-list, pin the version, done. No PHP extension requirements, no migrations, no external services, no credentials.
• Effort is genuinely small: roughly 0.5–1.5 engineer-days including a wrapper service, caching, a Rule object for validation, a Blade/Inertia select component, and tests.
• Verify during the spike: the exact data directory layout and file naming convention (locale directory vs. format directory, extension, flat map vs. nested), whether native/autonym names are included alongside translated names, and whether the payload uses en-US or en_US style codes. These details determine the normalization code we write around it.

Technical risk

• Low runtime risk. No code executes; the blast radius of a bad version is a malformed or missing data file, not a crash in shared infrastructure. Failures are contained to the locale-picker feature.
• Primary risk is data governance, not engineering. The dataset is a generated snapshot derived from upstream locale standards (CLDR/ICU lineage). Freshness lags upstream releases, and the package's own release cadence is slow. The MIT license covers the package; the embedded data may carry separate upstream terms — worth a five-minute legal check before shipping it in a distributed product.
• Secondary risk is coverage mismatch. Product requirements often need region variants (pt-BR, zh-Hans, sr-Latn) and POSIX-style codes for OS integration. A generic locale list may not carry every variant we care about, or may carry far more than the product supports.
• Low maintainer risk, but non-zero. 319 stars and a slow cadence mean we should treat it as vendorable source: if it goes stale, we fork the data or replace the source rather than wait.

Key questions

1. Is our product's source of truth for "supported locales" this dataset, or a curated subset we maintain? (Recommendation: curated subset in config, package as the display-name provider.)
2. Do we need BCP-47 region/script variants for the locales we ship, and does the dataset's coverage match?
3. What upstream release is the data pinned to, and what is our acceptable staleness window?
4. Do we need autonyms (native names) in addition to translated names for the language switcher?
5. Are we comfortable shipping the full multi-format dataset in the deploy artifact, or do we prune to the one format we use?
6. Who owns the refresh cadence and the fallback policy when a requested locale is absent?

Integration Approach

Stack fit

• Framework-agnostic and PHP-version-tolerant; fits Laravel 10/11/12 with no constraints beyond Composer. Nothing to register in config/app.php or bootstrap/providers.php.
• The idiomatic Laravel shape is a thin service: LocaleRepository::all(string $displayLocale): array, ::name(string $code, string $displayLocale): ?string, ::isSupported(string $code): bool. Bind it as a singleton; back it with Cache::rememberForever() or an in-process static so the file is decoded once per request/worker.
• Expose it externally through a Rule (validates locale code on registration/profile update), a Blade component (select options), and optionally an API resource for the frontend to fetch options once and cache client-side.

Migration path

• From hardcoded arrays: mechanical replacement; keep the same output shape so call sites don't change.
• From PHP intl / Locale::getDisplayName(): this is a determinism-vs-freshness trade. intl follows the server's ICU version (non-deterministic across environments); the package gives an identical snapshot everywhere. Prefer the package where reproducible behavior matters; prefer intl where freshest coverage matters. Do not use both.
• From symfony/intl: that library offers a richer API (scripts, territories, variants) with more maintenance weight. If we only need code → name, the flat dataset is the lighter dependency.
• Rollback is trivial: revert the Composer lock entry and delete the wrapper. No data migration, no dual-write concerns.

Compatibility

• Watch three seams: code format (en-US vs en_US — add an explicit normalizer), case sensitivity on the code used as a lookup key, and display-locale fallback when the requested display language is missing (fall back to en, then to the code itself).
• If locale codes are persisted in the database, add a validation rule at the boundary so un-normalized codes never reach storage. Existing rows may need a one-time backfill.

Sequencing

1. Spike (0.5 day): install, inspect file layout, confirm coverage for our target locale set, measure vendor footprint.
2. Abstraction (0.5 day): LocaleRepository + caching + normalization + fallback, with unit tests covering missing files and unknown codes.
3. Adoption (0.5 day): swap the locale picker and add the validation rule; delete hardcoded lists.
4. Hardening: pin the exact version in composer.json, add a test asserting the supported-locale subset resolves to a non-null name (catches silent data regressions on upgrade), and record the refresh owner.
5. Optional: prune to a single serialization format at build time if artifact size becomes a concern.

Operational Impact

Maintenance

• Near-zero code maintenance: no runtime surface to patch. The real maintenance is data currency — a recurring (semi-annual is generous) check that the upstream snapshot hasn't drifted in a way that matters to us. This should be a named owner and a calendar item, not a hope.
• Upgrade cost per version bump is a PR + test run. Treat minor/patch bumps as routine, and read the diff on major bumps.

Support

• No vendor, no SLA, no support channel. Escalation path is "we fork the data." Given the package is essentially a generated directory tree, a fork is cheap and should be pre-approved as the contingency rather than escalated later.
• Internal support burden concentrates on semantics: "why does this locale show as Português (Brasil) here and Portuguese (Brazil) there?" Document the display-locale fallback chain once and point to it.

Scaling

• Effectively free. Reads are local file I/O, then memory. Decode once per process (safe under Octane/FrankenPHP with a static or a container singleton) or cache the parsed array in Redis if worker memory is tight.
• Do not call file_get_contents + json_decode per request in a hot path — that's the only realistic way to make this slow. For a select rendered once per page, even the naive version is acceptable.
• Frontend scaling: serve the option list via a cacheable endpoint or inline it into the initial payload; it's a few KB for a curated subset.

Failure modes

• Missing file for a display locale → blank picker or exception. Mitigate with a fallback chain and a test that iterates every supported locale.
• Unknown/unsupported code at validation → rejected user input; ensure the error message is human-readable and the list of accepted codes is surfaced in the UI rather than only in the 422 body.
• Upstream data drift on upgrade (renamed territory, changed endonym) → snapshot tests on a small fixture set catch it.
• Oversized artifact → slow cold deploys, bloated container images. Mitigate by pruning to one format if measured.
• Silent license/attribution omission → surfaced only at distribution or legal review. Check early.
• Code-format mismatch (_ vs -) → lookups silently return null and the UI degrades without erroring. Normalize at the boundary and assert it in tests.

Ramp-up

• Any Laravel developer can be productive here in under an hour; there is no new mental model beyond "it's a folder of JSON."
• Onboarding cost is in the wrapper's conventions (normalization, fallback, supported subset), which is exactly why the wrapper should be small, tested, and documented in one place. Avoid letting raw vendor paths leak into controllers, views, or models.