Laravel langsys/langsys-php-laravel

Une fine couche d'intégration Laravel au-dessus de langsys/langsys-php : la directive Blade @t, le helper t() et un middleware de locale. La phrase dans votre code sert à la fois de clé de recherche et de texte par défaut dans la langue de base — pas de fichier de clés, pas d'étape d'extraction. La traduction s'effectue côté serveur : la page arrive donc déjà localisée.

SDK backend, donc pas de playground dans le navigateur sur cette page — le navigateur ne peut pas exécuter PHP. L'application de démo est la version interactive de chaque exemple ci-dessous : clonez-la et lancez php artisan serve, ou ouvrez-la dans un Codespace — un vrai conteneur PHP qui l'installe et la sert pour vous. La référence complète du package, y compris la traduction automatique des pages et l'initialisation d'Inertia, se trouve dans la documentation du SDK Laravel.

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.

Installer

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

Pas encore de projet ni de clés ? Le démarrage rapide vous fournit les deux en deux minutes.

Middleware

Deux middlewares assurent le travail côté framework : DetectLocale détermine la langue du visiteur (paramètre de requête, cookie, session, puis Accept-Language) et conserve son choix ; FlushPendingRegistrations envoie les nouvelles phrases détectées à Langsys après l'envoi de la réponse, de sorte que l'enregistrement ne ralentit jamais une page.

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

Traduire dans Blade

Une seule directive : @t(phrase, category?, params?, locale?). Les paramètres s’interpolent avec les marqueurs {name} — les nombres et les dates sont formatés selon la locale — et la sortie est échappée en HTML.

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

N'importe où en PHP

@t n'est que l'assistant t() avec échappement — l'assistant lui-même fonctionne partout : contrôleurs, composants Livewire, jobs, e-mails, messages de validation.

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

Pluriels

Écrivez la phrase à plat : Langsys génère les formes plurielles de chaque locale pendant la traduction — y compris la locale de base — et le SDK affiche la branche correspondant à votre nombre (ICU complet via ext-intl). C’est identique dans tous les SDK, ce qui permet de réutiliser les phrases entre votre backend et votre 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]);

Les formes plurielles générées par Langsys arrivent dans PHP à partir de langsys/langsys-php 1.3.2 ; les versions antérieures affichent la forme du pluriel pour tous les nombres, y compris 1.

Accord en genre

L'espagnol, le français ou le russe accordent {username} has been invited selon la personne concernée. Langsys génère ces variantes pendant la traduction — comme il génère les pluriels — et l'argument porte le nom de la variable, suivi de _gender : male, female ou other. Transmettez-le dès que vous le connaissez. Comment cela fonctionne, et comment repérer les phrases concernées →

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

Vous ne connaissez pas le genre ? Transmettez 'other' explicitement — c'est la variante neutre. Si elle est tout de même absente, le SDK de base utilise automatiquement la variante other (langsys/langsys-php 1.3.1 et versions ultérieures, avec ou sans ext-intl), de sorte que la phrase reste correcte.

Catégories

La catégorie délimite le périmètre d'une phrase : les mêmes mots peuvent ainsi être traduits différemment selon le contexte.

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

Lequel dois-je utiliser ?

Règle générale : Blade → @t · PHP → t() · intouchable → ne pas l'encadrer.

Découverte des jetons côté serveur

Lorsque vous affichez une phrase que Langsys ne connaît pas encore, elle est mise en file d'attente, puis enregistrée une fois la réponse terminée — le visiteur voit immédiatement votre texte dans la langue de base, et la phrase apparaît dans votre tableau de bord, prête à être traduite. Cela nécessite une clé write ; avec une clé en lecture seule, la mise en file d'attente est ignorée silencieusement, ce qui est exactement ce qu'il faut dans les environnements qui ne doivent pas modifier le catalogue.

Association avec les SDK JS

Vous utilisez Inertia ou une application hybride ? Transmettez aux SDK JS le catalogue que le serveur a déjà récupéré, pour que le client ne le télécharge pas une seconde fois : c'est le même transfert initialTranslations que décrivent les pages des SDK frontend.

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

La façade et le client brut

La façade Langsys reprend t(), et Langsys::client() vous donne le client langsys/langsys-php sous-jacent pour tout ce qui dépasse la recherche de phrases : lecture du catalogue, contrôle du cache, blocs de contenu.

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