Native Locale Names Laravel Package

Product Decisions This Supports

Language switcher / locale selector UX. This package answers one narrow but highly visible product question: what do we call each language in the picker? Shipping "Deutsch" next to "Русский" and "日本語" instead of "German / Russian / Japanese" is a recognized localization-quality signal. Users who can't read the UI language need to find their own language in its own script — this is the single most common reason locale switchers fail usability review.

Build vs. buy for a 40-line problem. The alternative is a hand-maintained array in config/app.php, an intl Locale::getDisplayName() call, or a spreadsheet someone exports once and nobody updates. The package's value proposition is not code, it is curated, continuously refreshed CLDR-derived data. Framing it as "buy the data, not the code" makes the decision easy: we are not adopting a framework dependency, we are outsourcing a small content-maintenance burden.

Roadmap: internationalization expansion. Every new locale we add to the roadmap is a new label we'd otherwise have to source, spell-check, and keep correct (including variants like pt-BR vs pt-PT and script variants). This package de-risks incremental locale rollout — adding a market becomes a config change in our allow-list rather than a content project with a translation vendor.

Feature scoping: where the package does not decide for us. Three product decisions remain ours and should be made explicitly, not inherited:

• Locale scope — do we expose bare languages ("Portuguese") or regions ("Português (Brasil)")? This is a market-positioning call, not a technical one.
• Sort order — sorting is disabled by default (since 2.1.0). Alphabetical-by-English-name, alphabetical-by-endonym, and "by user's own locale collation" are three different products. Someone must own this decision, or we ship a picker in code-point order.
• Fallback behavior — what renders when a locale is in our allow-list but absent from the data. Silent null in a dropdown is a user-visible bug.

Adjacent surfaces as scope creep guardrails. If the selector ships, the same labels will be requested for admin screens, email footers, and marketing pages. Deciding up front whether this package is the single source of truth across all surfaces (recommended) or only the app prevents three divergent label sets six months out.

Not a decision this supports: translation of content, locale negotiation/detection, timezone or currency formatting, or ICU-grade collation. Do not let a "we added i18n support" narrative overpromise on the back of a label-only package.

When to Consider This Package

Adopt when:

• You are shipping or already have a language switcher, language preference settings page, or locale-aware onboarding.
• Your supported locale set is roughly in the dozens and generally aligns with CLDR/laravel-lang coverage (Laravel's standard locale ecosystem, now including recent additions such as Haitian Creole and Canadian variants).
• You want deterministic output that doesn't change with the server's ICU version — a real advantage over intl when you have multiple environments, containers, or a mix of distros.
• You are already in the Laravel-Lang family (e.g., using laravel-lang/lang or laravel-lang/locale-list), in which case this is a near-zero-marginal-cost add and the dependency graph is already present.
• You can commit to a thin internal wrapper (a config allow-list plus one accessor class) — and you should, regardless of package choice.

Look elsewhere / do it manually when:

• You support one to five locales. A literal array is clearer, reviewable, and has zero supply-chain risk. The package earns its keep at breadth, not depth.
• You need locale-aware sorting as a first-class requirement. Sorting here is off by default and is not ICU collation. If the product promise is "a properly ordered picker for every locale," budget for intl collation on top, or expect to solve it yourself.
• Your locale set is off-catalog — internal dialect codes, custom regional groupings, or labels your brand dictates ("Chinese (Simplified)" vs "简体中文"). You'll be overriding more than you inherit.
• You need accessibility-adjacent metadata — flags, right-to-left flags, script directionality, or language-to-region mapping. This package is names only; plan a second source.
• Supply-chain posture is strict. With 7 stars, 0 dependents, and effectively a bus factor of one maintainer plus a GitHub Actions bot, teams with hard dependency-review gates should expect a fight. The mitigating fact — Laravel-Lang organization backing, MIT license, and a data set that is trivially forkable — is the argument to make, not to skip.
• You require frozen, audited labels. Automated data releases (e.g., 2.7.0 / 2.9.0, pure bot-driven updates) mean minor bumps can silently change user-visible strings. Acceptable if you pin and snapshot-test; unacceptable if you can't.

Adoption preconditions to verify before committing: PHP 8.1+, Laravel 11–13 (>=2.8.0 for Laravel 13), no conflicting laravel-lang/locale-list major version already installed, and a documented fallback contract for missing keys.

How to Pitch It (Stakeholders)

To executives — one paragraph. We're adding a dependency-free data package that gives us the correct name of every language in that language — "Deutsch," "Русский," "日本語" — for our language selector and settings screens. It's maintained by the Laravel-Lang organization, the de facto standard for Laravel localization data, is MIT-licensed, and replaces a hand-maintained list that goes stale every time we add a market. Cost is hours of engineering, not days; the risk is small and containable because the data is static, forkable, and behind our own abstraction layer. What I need from you is not a go/no-go on the library but a decision on product scope: which locales we expose and whether we sort them by the user's own language order.

To engineering — the ask. Adopt it, but do not call the static class from views. Wrap it: a versioned config/locales.php allow-list as our source of truth, and a single LocaleNameRepository that merges allow-list + labels and enforces sort order and fallback. That's ~50 lines and it means a swap to intl or a fork is a one-file change. Three things need explicit decisions and tests:

1. Fallback contract — verify and standardize what happens on a missing key (null, exception, or raw code). Silent nulls in a dropdown are a shipped bug.
2. Sorting — disabled by default since 2.1.0; decide and implement deliberately, and tell me whether intl is available for locale-aware collation.
3. Pinning + snapshot test — caret within v2 plus a test asserting the rendered label set for every supported locale, so bot-driven data releases fail a test instead of surprising a user.

Also flag: the 2.x namespace rename (Native → LocaleNames) means any snippet found online pre-2.x is wrong, and the likely install failure is a laravel-lang/locale-list major-version conflict.

To design/UX — the review artifact. Expect visible label diffs on day one, especially for region and script variants. Treat the first render as a UX review, not a regression: this is our one chance to confirm the endonyms match how our target markets actually refer to themselves.

The honest caveat to keep in the room. This package solves labels, not localization. It does not translate content, detect user locale, format dates or currency, or sort properly for every language. Success criterion should be stated narrowly — "users can find their own language in the switcher" — so the win is measurable and the scope doesn't quietly expand into a full i18n program on the back of a 7-star data library.