Lingua Laravel Package

Getting Started

Install via Composer and rely on Laravel's package auto-discovery (the service provider and Lingua facade are registered automatically in Laravel 5.5+):

composer require whitecube/lingua

The entry point is the WhiteCube\Lingua\Lingua facade. The mental model is a fluent converter: you declare what you have with a fromX() call, then ask for what you want with a toX() call.

use WhiteCube\Lingua\Lingua;

Lingua::from('en')->toIso639_1();   // "en"
Lingua::from('german')->toIso639_1(); // "de"
Lingua::from('de')->toName();       // "German"
Lingua::from('de')->toNative();     // "Deutsch"
Lingua::from('eng')->toIso639_1();  // "en"

First useful use case: normalizing language codes coming from user input, CSV imports, or third-party APIs before persisting them. In a migration, import job, or form request, funnel every value through the package and store a single canonical form (usually ISO 639‑1), so the rest of the app never has to juggle en / eng / English / english.

Publish/consult the config only if you need to override the bundled language dataset:

php artisan vendor:publish --provider="WhiteCube\Lingua\LinguaServiceProvider"

Implementation Patterns

Canonical storage + conversion at the edges. Pick one code format for your database (ISO 639‑1 is the most readable) and convert only at ingest and render time. A small value object or accessor encapsulates this:

protected function languageCode(?string $input): ?string
{
    try {
        return Lingua::from($input)->toIso639_1();
    } catch (\Throwable $e) {
        return null; // or log + fallback
    }
}

Form select options. Build a language picker by iterating the repository's language list and mapping each entry to [code => native name]. Cache the generated array (see below) — it is static data.

$options = collect($repository->all())
    ->mapWithKeys(fn ($lang) => [
        $lang->toIso639_1() => $lang->toNative(),
    ]);

Validation rule. Wrap the converter in a custom rule so "German", "de", and "deu" all pass, but "klingon" fails:

public function passes($attribute, $value)
{
    try {
        Lingua::from($value)->toIso639_1();
        return true;
    } catch (\Throwable $e) {
        return false;
    }
}

Accept-Language negotiation. Parse the header, split on ,, strip ;q= weights and any -REGION suffix (the package deals in languages, not full BCP‑47 locales), then use it to match against your supported set. This is where the package earns its keep in a multi-language app.

Locale → language mapping. If you store Laravel locales like de_DE or pt-BR, take the leading segment (de, pt) and feed that to Lingua::from(...). Do not pass the full locale string — the package has no concept of regions.

Caching and DI. Conversion is cheap (in-memory arrays), but the repository is built from static data — bind it as a singleton or cache the derived option arrays with Cache::remember. In tests, resolve the facade directly rather than rebuilding per call.

Gotchas and Tips

• Ambiguity of from(). It guesses the source format from the string. "en" is unambiguous, but some 3-letter strings collide across ISO 639‑2/639‑3, and some names match multiple entries. Where it matters, use the explicit fromIso639_1() / fromIso639_2() / fromIso639_3() / fromName() helpers instead of the auto-detecting from().
• ISO 639‑2 bibliographic vs. terminological. Codes like ger/deu, fre/fra, dut/nld are the same language with two valid ISO 639‑2 forms. Decide which your app emits and be consistent; libraries and legacy systems will send the other one.
• Not every language has an ISO 639‑1 code. Many ISO 639‑3 entries have no 2-letter form (e.g., most regional/indigenous languages). Calling toIso639_1() on those will fail or return empty — guard it and fall back to the 3-letter code.
• No region/script support. It is a language code converter, not a locale library. pt-BR vs pt-PT, zh-Hans vs zh-Hant, and sr-Latn are outside its scope. Keep region handling in your own layer (or a dedicated locale package) and only use Lingua for the language subtag.
• Case and whitespace. Normalize input (trim, and be mindful the dataset is mostly lowercase) before calling. Non-ASCII native names (Deutsch, 日本語, Français) are returned as-is — ensure your DB column and JSON responses are UTF‑8 (utf8mb4).
• Exception handling is on you. Unknown inputs throw; there is no tryFrom()-style nullable API. Wrap conversions, especially anything driven by request data, and log failures rather than letting a 500 escape from a form field.
• Maintenance risk (last release 2021, PHP‑7 era). Verify PHP 8.x compatibility and the Laravel auto-discovery / provider signatures against your framework version. If you hit deprecations, pin the package or vendor the small dataset locally — the core is just static arrays, so replacing it is low-effort.
• Custom data via config. If your domain needs languages or names outside the bundled set, extend/publish the dataset rather than hard-coding a mapping table in your own code — that keeps the extension point in one place.