Skip to main content

Laravel-i18n: Vollständiger Leitfaden zur Internationalisierung und Lokalisierung

Von der ersten Locale-Datei bis zur Produktion: Konfigurieren Sie Laravels Übersetzungssystem, verarbeiten Sie Pluralformen, beheben Sie den JSON-Fallback-Fehler und ergänzen Sie intelligente Locale-Fallback-Ketten für regionale Varianten.

1

Laravels Übersetzungssystem verstehen

Laravel enthält ein Übersetzungssystem für zwei Dateiformate: PHP-Arrays und JSON. PHP-Dateien verwenden nach Funktion gegliederte verschachtelte Schlüssel (auth.failed, validation.required). JSON-Dateien verwenden die Ausgangszeichenfolge als Schlüssel; dies ist einfacher, unterstützt aber keine Verschachtelung.

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
Laravels Übersetzungssystem befindet sich im Verzeichnis lang/ (Laravel 9+) oder resources/lang/ (Laravel 8 und älter). Das Framework erkennt das Verzeichnis automatisch. Sind beide vorhanden, hat lang/ Vorrang.
2

Locale-Einstellungen konfigurieren

Legen Sie die Standard- und Fallback-Locale Ihrer Anwendung in config/app.php fest. Die Fallback-Locale wird bei einem fehlenden Übersetzungsschlüssel in der aktiven Locale verwendet. Konfigurieren Sie unterstützte Locales und fügen Sie Middleware hinzu, um die bevorzugte Locale zu erkennen und zu setzen.

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

Übersetzungsfunktionen verwenden

Laravel bietet drei Übersetzungswege: die Hilfsfunktion __() (empfohlen), trans() und die Blade-Direktive @lang. Alle drei akzeptieren den Übersetzungsschlüssel und optionale Ersetzungsparameter. Verwenden Sie __() in PHP-Code und Blade-Vorlagen; nutzen Sie @lang in Blade, wenn HTML nicht maskiert werden soll.

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',
    ],
];
Bevorzugen Sie in neuem Code __() vor trans(). __() funktioniert mit PHP- und JSON-Übersetzungsdateien, trans() nur mit PHP-Dateien. Die Direktive @lang entspricht {'{ __() }'} in Blade-Vorlagen, besitzt aber eine etwas übersichtlichere Syntax.
4

Pluralformen verarbeiten

Laravel verwendet durch senkrechte Striche getrennte Pluralformen. Die einfachste Form lautet 'apples' => 'There is one apple|There are many apples'. Verwenden Sie für ausdrückliche Bereiche 'apples' => '{0} No apples|{1} One apple|[2,*] :count apples'. Die Hilfsfunktion trans_choice() oder Str::plural() wählt anhand der Anzahl die richtige Form.

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"
}
Laravels integrierte Pluralbildung verarbeitet bei den meisten Sprachen nur einfache one/other-Regeln korrekt. Für Sprachen mit komplexen Pluralformen – Arabisch hat sechs, Russisch vier und Polnisch drei – müssen Sie sämtliche erforderlichen CLDR-Pluralkategorien definieren. Andernfalls erscheint grammatikalisch falscher Text.
5

Locale-Fallback-Ketten hinzufügen

Laravels integrierter Fallback wechselt nur von der aktiven Locale zu fallback_locale – es gibt keinen Zwischenschritt. Eine Person mit pt-BR sieht bei einem fehlenden Schlüssel Englisch statt der vollständig geeigneten pt-PT-Übersetzung. laravel-locale-chain behebt dies, indem es Übersetzungen beim Laden aus einer konfigurierbaren Fallback-Kette rekursiv zusammenführt.

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

Übersetzungen automatisieren

Wenn Ihre Laravel-i18n-Einrichtung abgeschlossen ist, übersetzen Sie Ihre Locale-Dateien mit KI. Verweisen Sie Ihren KI-Assistenten auf die Datei der Ausgangs-Locale oder verwenden Sie die CLI von i18n Agent in Ihrer CI/CD-Pipeline. PHP- und JSON-Übersetzungsdateien werden unterstützt.

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
Übersetzen Sie schrittweise: Wenn Sie neue Schlüssel hinzufügen, übersetzen Sie nur die Änderungen, statt sämtliche Dateien neu zu erzeugen. So bleiben von Menschen geprüfte Übersetzungen erhalten und unnötige Änderungen werden vermieden.

Häufige Fallstricke

Fest codierte Singular-/Plurallogik

Der Ausdruck $count == 1 ? 'item' : 'items' statt trans_choice() funktioniert nicht in Sprachen, in denen 0 Singular ist (Französisch), mindestens drei Pluralformen existieren (Russisch, Polnisch) oder sechs Formen vorkommen (Arabisch). Verwenden Sie stets Laravels Pluralsyntax und definieren Sie alle erforderlichen Formen.

JSON-Übersetzungen besitzen keinen Fallback

Laravels fallback_locale funktioniert nur für PHP-Übersetzungsdateien. JSON-Übersetzungen verwenden die Ausgangszeichenfolge als Schlüssel, sodass eine fehlende Übersetzung den Schlüssel selbst, also den englischen Text, zurückgibt, statt in der Fallback-Locale zu suchen. JSON-Übersetzungen besitzen daher keinen echten Locale-Fallback. Beheben Sie dies mit laravel-locale-chain.

PHP und JSON mischen, ohne den Vorrang zu kennen

Wenn derselbe Schlüssel in PHP- und JSON-Dateien vorhanden ist, hat PHP Vorrang. Dadurch können verwirrende Situationen entstehen, in denen eine Änderung der JSON-Datei wirkungslos bleibt, weil die PHP-Datei sie überschattet. Wählen Sie pro Funktionsnamensraum ein Format und verwenden Sie es konsistent.

i18n Agent jetzt testen

Legen Sie Ihre Übersetzungsdatei hier ab

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

oder zum Auswählen klicken

Zielsprachen

Keine Registrierung erforderlichSofortiges Angebot

Häufig gestellte Fragen zu Laravel-i18n