Skip to main content

Laravel i18n: complete handleiding voor internationalisatie en lokalisatie

Van je eerste localebestand tot productie: configureer het vertaalsysteem van Laravel, verwerk meervoudsvormen, los de JSON-terugvalfout op en voeg slimme terugvalketens toe voor regionale varianten.

1

Het vertaalsysteem van Laravel begrijpen

Laravel heeft een ingebouwd vertaalsysteem dat twee bestandsindelingen ondersteunt: PHP-arrays en JSON. PHP-bestanden gebruiken geneste sleutels die per functie zijn geordend (auth.failed, validation.required). JSON-bestanden gebruiken de brontekst als sleutel. Dat is eenvoudiger, maar ondersteunt geen nesten.

Terminal
composer create-project laravel/laravel my-app
cd my-app

# Laravel includes i18n out of the box
# No extra packages needed for basic usage
Het vertaalsysteem van Laravel staat in de map lang/ (Laravel 9+) of resources/lang/ (Laravel 8 en ouder). Het framework detecteert de map automatisch. Als beide bestaan, krijgt lang/ voorrang.
2

Locale-instellingen configureren

Stel de standaardlocale en terugvallocale van je toepassing in config/app.php in. De terugvallocale wordt gebruikt wanneer een vertaalsleutel in de actieve locale ontbreekt. Configureer de ondersteunde locales en voeg middleware toe die de voorkeurslocale van de gebruiker detecteert en instelt.

config/app.php
// config/app.php
return [
    'locale' => 'en',            // Default locale
    'fallback_locale' => 'en',   // Fallback when key is missing
    'faker_locale' => 'en_US',

    // Available locales (for your language switcher)
    'available_locales' => ['en', 'de', 'ja', 'es', 'fr', 'pt-BR'],
];
app/Http/Middleware/SetLocale.php
// app/Http/Middleware/SetLocale.php
namespace App\Http\Middleware;

use Closure;
use Illuminate\Http\Request;

class SetLocale
{
    public function handle(Request $request, Closure $next)
    {
        $locale = $request->segment(1); // e.g. /de/about

        if (in_array($locale, config('app.available_locales'))) {
            app()->setLocale($locale);
        }

        return $next($request);
    }
}
3

Vertaalfuncties gebruiken

Laravel biedt drie manieren om tekenreeksen te vertalen: de hulpfunctie __() (aanbevolen), de functie trans() en de Blade-richtlijn @lang. Alle drie accepteren de vertaalsleutel en optionele vervangingsparameters. Gebruik __() in PHP-code en Blade-sjablonen en @lang in Blade wanneer je HTML niet hoeft te escapen.

lang/en/messages.php
// lang/en/messages.php
return [
    'welcome' => 'Welcome to our application',
    'greeting' => 'Hello, :name!',
    'nav' => [
        'home' => 'Home',
        'about' => 'About',
        'settings' => 'Settings',
    ],
];

// lang/de/messages.php
return [
    'welcome' => 'Willkommen in unserer Anwendung',
    'greeting' => 'Hallo, :name!',
    'nav' => [
        'home' => 'Startseite',
        'about' => 'Über uns',
        'settings' => 'Einstellungen',
    ],
];
Geef in nieuwe code de voorkeur aan __() boven trans(). __() werkt met zowel PHP- als JSON-vertaalbestanden, terwijl trans() alleen met PHP-bestanden werkt. In Blade-sjablonen is de richtlijn @lang gelijkwaardig aan {'{ __() }'}, maar de syntaxis is iets overzichtelijker.
4

Meervoudsvormen verwerken

Laravel gebruikt een door sluistekens gescheiden syntaxis voor meervoudsvormen. De eenvoudigste vorm is 'apples' => 'There is one apple|There are many apples'. Gebruik voor expliciete bereiken 'apples' => '{0} No apples|{1} One apple|[2,*] :count apples'. De hulpfunctie trans_choice() of Str::plural() selecteert op basis van het aantal de juiste vorm.

lang/en.json
// lang/en.json
{
    "Welcome back!": "Welcome back!",
    "You have :count new notifications": "You have :count new notifications",
    "Copyright :year :company": "Copyright :year :company"
}

// lang/de.json
{
    "Welcome back!": "Willkommen zurück!",
    "You have :count new notifications": "Sie haben :count neue Benachrichtigungen",
    "Copyright :year :company": "Copyright :year :company"
}
De ingebouwde meervoudsverwerking van Laravel verwerkt voor de meeste talen alleen eenvoudige regels voor één/overig correct. Voor talen met complexe meervoudsvormen (Arabisch heeft er 6, Russisch 4 en Pools 3) moet je alle vereiste CLDR-meervoudscategorieën definiëren. Anders zien gebruikers grammaticaal onjuiste tekst.
5

Locale-fallbackketens toevoegen

De ingebouwde terugval van Laravel gaat alleen van de actieve locale naar fallback_locale; er is geen tussenstap. Een gebruiker met pt-BR en een ontbrekende sleutel ziet Engels in plaats van de prima vertaling voor pt-PT. laravel-locale-chain verhelpt dit door vertalingen uit een configureerbare terugvalketen tijdens het laden diep samen te voegen.

resources/views/example.blade.php
{{-- Simple translation --}}
<h1>{{ __('messages.welcome') }}</h1>

{{-- With variables --}}
<p>{{ __('messages.greeting', ['name' => $user->name]) }}</p>

{{-- Using @lang directive --}}
<h2>@lang('messages.nav.home')</h2>

{{-- JSON translations (use the string itself as key) --}}
<p>{{ __('Welcome back!') }}</p>

{{-- Pluralization --}}
{{ trans_choice('{0} No items|{1} One item|[2,*] :count items', $count) }}

{{-- Inside Blade components --}}
<x-button>{{ __('messages.nav.settings') }}</x-button>
6

Vertalingen automatiseren

Nu je Laravel-i18n-configuratie klaar is, kun je de localebestanden met AI vertalen. Laat je AI-assistent het bronlocalebestand verwerken of gebruik de CLI van i18n Agent in je CI/CD-pipeline. Zowel PHP- als JSON-vertaalbestanden worden ondersteund.

config/locale-chain.php
// Install locale chain package
composer require i18n-agent/laravel-locale-chain

// config/locale-chain.php
return [
    'chains' => [
        'pt-BR' => ['pt-BR', 'pt', 'en'],
        'zh-Hant-TW' => ['zh-Hant-TW', 'zh-Hant', 'zh', 'en'],
        'es-419' => ['es-419', 'es', 'en'],
    ],
];

// In AppServiceProvider::boot()
use I18nAgent\LocaleChain\LocaleChainServiceProvider;

// The package automatically deep-merges translations
// across the chain: pt-BR -> pt -> en
Vertaal stapsgewijs: vertaal bij nieuwe sleutels alleen het verschil in plaats van alle bestanden opnieuw te genereren. Zo blijven door mensen beoordeelde vertalingen behouden en voorkom je onnodige wijzigingen.

Veelvoorkomende valkuilen

Hardgecodeerde logica voor enkelvoud en meervoud

Als je $count == 1 ? 'item' : 'items' schrijft in plaats van trans_choice() te gebruiken, werkt de tekst niet voor talen waarin 0 enkelvoud is (Frans), die meer dan 3 meervoudsvormen hebben (Russisch, Pools) of die 6 vormen hebben (Arabisch). Gebruik altijd de meervoudssyntaxis van Laravel en definieer alle vereiste vormen.

JSON-vertalingen vallen niet terug

De fallback_locale van Laravel werkt alleen voor PHP-vertaalbestanden. JSON-vertalingen gebruiken de brontekst als sleutel, waardoor een ontbrekende vertaling de sleutel zelf (de Engelse tekst) retourneert in plaats van in de terugvallocale te zoeken. JSON-vertalingen hebben dus geen echte localeterugval. Los dit op met laravel-locale-chain.

PHP en JSON combineren zonder de voorrang te begrijpen

Als dezelfde sleutel in zowel PHP- als JSON-bestanden voorkomt, krijgt PHP voorrang. Dat kan verwarrend gedrag veroorzaken: een wijziging in het JSON-bestand heeft geen effect omdat het PHP-bestand de sleutel overschrijft. Kies per functienaamruimte één indeling en houd je daaraan.

Probeer i18n Agent nu

Zet je vertaalbestand hier neer

JSON, YAML, PO, XML, CSV, Markdown, Properties

of klik om een bestand te selecteren

Doeltalen

Geen registratie nodigDirecte prijsindicatie

Veelgestelde vragen over Laravel i18n