Laravel langsys/langsys-php-laravel

Eine schlanke Laravel-Anbindung an langsys/langsys-php: die Blade-Direktive @t, der Helper t() und Locale-Middleware. Die Formulierung in Ihrem Code ist zugleich Lookup-Schlüssel und Standardtext in der Basissprache – keine Schlüsseldatei, kein Extraktionsschritt. Die Übersetzung erfolgt auf dem Server, sodass die Seite bereits lokalisiert ausgeliefert wird.

Backend-SDK, daher gibt es auf dieser Seite keinen Playground im Browser – der Browser kann kein PHP ausführen. Die Demo-App ist die Live-Version jedes Beispiels unten: Klonen Sie sie und führen Sie php artisan serve aus, oder öffnen Sie sie in einem Codespace – einem echten PHP-Container, der sie für Sie installiert und bereitstellt. Die vollständige Paketreferenz, einschließlich automatischer Seitenübersetzung und Inertia-Seeding, finden Sie in der Laravel-SDK-Dokumentation.

Add Langsys translation to this Laravel app.

1. Read https://docs.langsys.dev/llms.txt, then follow
   https://docs.langsys.dev/learn/sdk/laravel/ for the install and setup.
2. The English text in the code is the translation key. Wrap user-facing
   strings as they are: no keys file, no extraction step, and no
   hand-written plural or gender branches (Langsys generates those).
3. Read the Langsys project id and API key from environment variables.
   The write key is for development and servers only; anything shipped
   to the browser gets the read-only key.
4. Keep brand names and user-generated content out of translation.

Installieren

composer require langsys/langsys-php-laravel
php artisan vendor:publish --tag=langsys-config

# The server can hold a WRITE key — unlike a browser app, it's never
# shipped to visitors. A write key is what lets new phrases register.
LANGSYS_API_KEY=your-api-key
LANGSYS_PROJECT_ID=your-project-id

Noch kein Projekt und keine Schlüssel? Mit dem Schnellstart haben Sie beides in zwei Minuten.

Middleware

Zwei Middleware-Komponenten übernehmen die Framework-Arbeit: DetectLocale ermittelt die Locale des Besuchers (Query-Parameter, Cookie, Session, dann Accept-Language) und speichert dessen Auswahl; FlushPendingRegistrations sendet neu entdeckte Phrasen an Langsys, nachdem die Antwort ausgeliefert wurde, sodass die Registrierung eine Seite nie verlangsamt.

// bootstrap/app.php (Laravel 11/12)
->withMiddleware(function (Middleware $middleware) {
    $middleware->web(append: [
        // Resolves ?locale= / cookie / session / Accept-Language,
        // then persists the visitor's choice.
        \Langsys\Laravel\Http\Middleware\DetectLocale::class,
        // After the response is sent, registers any phrases
        // rendered for the first time.
        \Langsys\Laravel\Http\Middleware\FlushPendingRegistrations::class,
    ]);
})

In Blade übersetzen

Eine Direktive: @t(phrase, category?, params?, locale?). Parameter werden über {name}-Marker interpoliert – Zahlen und Datumsangaben werden lokalisiert formatiert –, und die Ausgabe wird HTML-escaped.

<h1>@t('Welcome to our store', 'Home')</h1>
<p>@t('Hello, {name}! You have {count} new messages.', 'Greetings',
    ['name' => $name, 'count' => $count])</p>

Überall in PHP

@t ist einfach der t()-Helper mit Escaping – der Helper selbst funktioniert überall: in Controllern, Livewire-Komponenten, Jobs, Mails und Validierungsmeldungen.

// Controllers, Livewire components, jobs, mail — anywhere:
$title = t('Order confirmed', 'Checkout');
$body  = t('Your order {id} ships on {date}.', 'Checkout', [
    'id'   => (string) $order->number, // strings skip number formatting
    'date' => $order->ships_at,        // DateTime → locale-formatted
]);

Pluralformen

Schreiben Sie den Satz einfach flach: Langsys erzeugt die Pluralformen jeder Locale bei der Übersetzung – einschließlich der Basis-Locale –, und das SDK rendert den Zweig, der zu Ihrer Anzahl passt (vollständiges ICU über ext-intl). In jedem SDK gleich, sodass Phrasen zwischen Backend und Frontend portabel bleiben.

// Written flat. Langsys generates each locale's plural forms during
// translation (the base locale included) and the SDK picks the branch.
t('You have {count} items in your cart', 'Cart', ['count' => $count]);

Die von Langsys generierten Pluralformen erreichen PHP ab langsys/langsys-php 1.3.2; frühere Versionen geben für jede Anzahl die Pluralform aus, auch für 1.

Genusübereinstimmung

Spanisch, Französisch oder Russisch flektieren {username} has been invited je nach der Person, um die es geht. Langsys generiert diese Varianten bei der Übersetzung – genauso wie Pluralformen – und das Argument trägt den Namen der Variablen mit angehängtem _gender: male, female oder other. Übergeben Sie es immer, wenn Sie es kennen. So funktioniert es und so finden Sie die Phrasen, die es benötigen →

{{-- Pass the agreement argument alongside the value it inflects. --}}
@t('{username} has been invited', 'Team', [
    'username'        => $post->author->name,
    'username_gender' => $post->author->gender, // 'male' | 'female' | 'other'
])

Sie kennen das Geschlecht nicht? Übergeben Sie 'other' ausdrücklich – das ist die neutrale Variante. Fehlt sie trotzdem, nimmt das Basis-SDK automatisch die Variante other (langsys/langsys-php ab Version 1.3.1, mit oder ohne ext-intl), sodass der Satz weiterhin korrekt klingt.

Kategorien

Die Kategorie grenzt eine Formulierung ein, sodass dieselben Wörter in unterschiedlichen Kontexten unterschiedlich übersetzt werden können.

{{-- Same word, two meanings — the category disambiguates. --}}
<strong>@t('Home', 'Main Menu')</strong>      {{-- "Inicio" --}}
<strong>@t('Home', 'Home repairs')</strong>   {{-- "Casa" --}}

Welches soll ich verwenden?

Faustregel: Blade → @t · PHP → t() · unantastbar → nicht umschließen.

Token-Erkennung auf dem Server

Wird eine Phrase gerendert, die Langsys noch nicht kennt, wird sie in eine Warteschlange gestellt und nach Abschluss der Antwort registriert – der Besucher sieht sofort Ihren Text in der Basissprache, und die Phrase erscheint in Ihrem Dashboard, bereit zur Übersetzung. Dafür ist ein Schreibschlüssel nötig; bei einem schreibgeschützten Schlüssel wird die Warteschlange stillschweigend übersprungen, was genau richtig ist für Umgebungen, die den Katalog nicht verändern sollen.

Kopplung mit den JS-SDKs

Du nutzt Inertia oder eine Hybrid-App? Übergib den JS-SDKs den Katalog, den der Server bereits abgerufen hat, damit der Client ihn nicht erneut abruft – dieselbe initialTranslations-Übergabe, die die Seiten zum Frontend-SDK beschreiben.

// app/Http/Middleware/HandleInertiaRequests.php
use Langsys\Laravel\Support\InertiaSsrProps;

public function share(Request $request): array
{
    return [...parent::share($request), ...InertiaSsrProps::share()];
}

// resources/js — Vue shown; same shape for React/Svelte
import { LangsysApp, useLocaleStore } from 'langsys-js-vue';

const { store } = useLocaleStore(props.langsys.initialTranslationsLocale);
LangsysApp.init({
    projectid: import.meta.env.VITE_LANGSYS_PROJECT_ID,
    key: import.meta.env.VITE_LANGSYS_API_KEY, // read-only key on the client
    UserLocaleStore: store,
    initialTranslations: props.langsys.initialTranslations,
    initialTranslationsLocale: props.langsys.initialTranslationsLocale,
});

Die Fassade & der Raw-Client

Die Langsys-Facade spiegelt t(), und Langsys::client() liefert Ihnen den zugrunde liegenden langsys/langsys-php-Client für alles jenseits des Phrasen-Lookups – Katalogabfragen, Cache-Steuerung, Inhaltsblöcke.

use Langsys\Laravel\Facades\Langsys;

Langsys::translate('Save', 'UI');            // same seam as t()
Langsys::client()->getTranslations('es-es'); // the vanilla langsys/langsys-php client
Langsys::client()->clearCache('es-es');      // pick up dashboard edits before the TTL