Laravel langsys/langsys-php-laravel

Un sottile binding per Laravel su langsys/langsys-php: la direttiva Blade @t, l'helper t() e il middleware per le lingue. La frase nel tuo codice è sia la chiave di ricerca sia il testo predefinito nella lingua di base: nessun file di chiavi, nessuna fase di estrazione. La traduzione avviene sul server, quindi la pagina arriva già localizzata.

SDK backend, quindi nessun playground nel browser in questa pagina: il browser non può eseguire PHP. La demo app è la versione live di ogni esempio qui sotto: clonala ed esegui php artisan serve, oppure aprila in un Codespace, un vero container PHP che la installa e la avvia per te. Il riferimento completo del pacchetto, inclusi la traduzione automatica delle pagine e il seeding di Inertia, si trova nella documentazione dell'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.

Installa

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

Non hai ancora un progetto o le chiavi? La guida rapida ti dà entrambi in due minuti.

Middleware

Due middleware svolgono il lavoro a livello di framework: DetectLocale determina la lingua del visitatore (parametro di query, cookie, sessione e infine Accept-Language) e ne memorizza la scelta; FlushPendingRegistrations invia a Langsys le frasi appena rilevate dopo l'invio della risposta, così la registrazione non rallenta mai una pagina.

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

Tradurre in Blade

Una sola direttiva: @t(phrase, category?, params?, locale?). I parametri si interpolano con i marcatori {name}: numeri e date vengono formattati in base alla lingua, e l'output è sottoposto a escape HTML.

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

Ovunque in PHP

@t è semplicemente l'helper t() con escaping — l'helper in sé funziona ovunque: controller, componenti Livewire, job, e-mail, messaggi di validazione.

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

Plurali

Scrivi la frase in forma semplice: Langsys genera le forme plurali di ogni lingua durante la traduzione, compresa la lingua di base, e l'SDK mostra il ramo che corrisponde al tuo conteggio (ICU completo tramite ext-intl). È così in ogni SDK, quindi le frasi restano portabili tra backend e 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]);

Le forme plurali generate da Langsys arrivano in PHP a partire da langsys/langsys-php 1.3.2; le versioni precedenti usano la forma plurale per qualsiasi conteggio, incluso 1.

Concordanza di genere

Spagnolo, francese o russo flettono {username} has been invited in base alla persona a cui ci si riferisce. Langsys genera queste varianti durante la traduzione — nello stesso modo in cui genera i plurali — e l'argomento prende il nome dalla variabile, con _gender aggiunto in coda: male, female oppure other. Passalo ogni volta che lo conosci. Come funziona e come trovare le frasi che ne hanno bisogno →

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

Non conosci il genere? Passa 'other' in modo esplicito: è la variante neutra. Se manca comunque, l'SDK di base usa per te la variante other (langsys/langsys-php 1.3.1 e successive, con o senza ext-intl), così la frase si legge comunque correttamente.

Categorie

La categoria definisce l'ambito di una frase, quindi le stesse parole possono essere tradotte in modo diverso in contesti diversi.

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

Quale devo usare?

Regola pratica: Blade → @t · PHP → t() · intoccabile → non racchiuderlo.

Rilevamento dei token sul server

Se visualizzi una frase che Langsys non ha mai visto, viene messa in coda e poi registrata dopo la chiusura della risposta: il visitatore vede subito il testo nella lingua di base e la frase compare nella tua dashboard, pronta per essere tradotta. Serve una chiave write; con una chiave di sola lettura la coda viene saltata silenziosamente, che è esattamente ciò che serve negli ambienti che non devono modificare il catalogo.

Abbinamento con gli SDK JS

Usi Inertia o un'app ibrida? Passa agli SDK JS il catalogo che il server ha già recuperato, così il client non lo scarica di nuovo: è lo stesso passaggio initialTranslations descritto nelle pagine dell'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 facade e il client raw

La facade Langsys rispecchia t(), e Langsys::client() ti dà il client langsys/langsys-php sottostante per tutto ciò che va oltre la ricerca delle frasi: lettura del catalogo, controllo della cache, blocchi di contenuto.

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