Laravel langsys/langsys-php-laravel

Een dunne Laravel-koppeling bovenop langsys/langsys-php: de Blade-directive @t, de helper t() en locale-middleware. De zin in je code is zowel de opzoeksleutel als de standaardtekst in de basistaal — geen sleutelbestand, geen extractiestap. De vertaling gebeurt op de server, dus de pagina komt al gelokaliseerd binnen.

Backend-SDK, dus geen playground in de browser op deze pagina: de browser kan geen PHP uitvoeren. De demo-app is de live versie van elk voorbeeld hieronder: kloon hem en voer php artisan serve uit, of open hem in een Codespace, een echte PHP-container die hem voor je installeert en serveert. De volledige pakketreferentie, inclusief automatische paginavertaling en Inertia-seeding, vind je in de documentatie van de Laravel-SDK.

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.

Installeren

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

Nog geen project of sleutels? Met de Snelstart heb je beide in twee minuten.

Middleware

Twee stukken middleware doen het frameworkwerk: DetectLocale bepaalt de locale van de bezoeker (queryparameter, cookie, sessie, daarna Accept-Language) en slaat hun keuze op; FlushPendingRegistrations stuurt nieuw ontdekte phrases naar Langsys nadat het antwoord is verzonden, zodat registratie een pagina nooit vertraagt.

// 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,
    ]);
})

Vertalen in Blade

Eén directive: @t(phrase, category?, params?, locale?). Params worden geïnterpoleerd met {name}-markeringen — getallen en datums komen er landspecifiek opgemaakt uit — en de uitvoer wordt 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>

Overal in PHP

@t is gewoon de t()-helper met escaping — de helper zelf werkt overal: controllers, Livewire-componenten, jobs, mail, validatiemeldingen.

// 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
]);

Meervoudsvormen

Schrijf de zin gewoon plat: Langsys genereert tijdens het vertalen de meervoudsvormen van elke locale — inclusief de basislocale — en de SDK rendert de tak die bij jouw aantal past (volledige ICU via ext-intl). Dit werkt in elke SDK hetzelfde, zodat zinnen overdraagbaar blijven tussen je backend en frontend.

// 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]);

De meervoudsvormen die Langsys genereert, bereiken PHP vanaf langsys/langsys-php 1.3.2; eerdere versies geven voor elk aantal de meervoudsvorm weer, ook bij 1.

Geslachtsovereenkomst

Spaans, Frans of Russisch verbuigen {username} has been invited naar de persoon over wie het gaat. Langsys genereert die varianten tijdens het vertalen — op dezelfde manier als meervoudsvormen — en het argument is vernoemd naar de variabele, met _gender erachter: male, female of other. Geef het mee wanneer je het weet. Hoe het werkt en hoe je de zinnen vindt die het nodig hebben →

{{-- 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'
])

Weet je het geslacht niet? Geef 'other' expliciet mee: dat is de neutrale variant. Ontbreekt die toch, dan neemt de basis-SDK automatisch de other-variant voor je (langsys/langsys-php 1.3.1 en later, met of zonder ext-intl), zodat de zin nog steeds goed leest.

Categorieën

De categorie bepaalt de reikwijdte van een zin, zodat dezelfde woorden in verschillende contexten anders vertaald kunnen worden.

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

Welke moet ik gebruiken?

Vuistregel: Blade → @t · PHP → t() · onaantastbaar → niet wrappen.

Token-detectie op de server

Als je een zin rendert die Langsys nog niet kent, komt die in de wachtrij en wordt hij geregistreerd nadat de respons is afgerond. De bezoeker ziet direct je tekst in de basistaal en de zin verschijnt in je dashboard, klaar om te vertalen. Hiervoor heb je een write-sleutel nodig; bij een alleen-lezen sleutel wordt de wachtrij stilzwijgend overgeslagen, precies wat je wilt in omgevingen die de catalogus niet mogen wijzigen.

Koppelen met de JS-SDK's

Gebruik je Inertia of een hybride app? Geef de JS-SDK's de catalogus die de server al heeft opgehaald, zodat de client hem niet opnieuw ophaalt. Het is dezelfde initialTranslations-overdracht die de pagina's over de frontend-SDK beschrijven.

// 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,
});

De facade & de ruwe client

De Langsys-facade spiegelt t(), en Langsys::client() geeft je de onderliggende langsys/langsys-php-client voor alles buiten het opzoeken van zinnen — catalogus lezen, cachebeheer, contentblokken.

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