Laravel langsys/langsys-php-laravel

Una capa delgada de Laravel sobre langsys/langsys-php: la directiva Blade @t, el helper t() y un middleware de configuración regional. La frase en tu código es a la vez la clave de búsqueda y el valor predeterminado en el idioma base: sin archivo de claves ni paso de extracción. La traducción ocurre en el servidor, así que la página llega ya localizada.

SDK de backend, así que esta página no tiene playground en el navegador: el navegador no puede ejecutar PHP. La app de demostración es la versión en vivo de cada ejemplo de abajo: clónala y ejecuta php artisan serve, o ábrela en un Codespace, un contenedor PHP real que la instala y la sirve por ti. La referencia completa del paquete, incluida la traducción automática de páginas y la precarga con Inertia, está en la documentación del SDK de 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.

Instalar

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

¿Aún no tienes proyecto ni claves? El Inicio rápido te da ambos en dos minutos.

Middleware

Dos piezas de middleware se encargan del trabajo del framework: DetectLocale determina la configuración regional del visitante (parámetro de consulta, cookie, sesión y, por último, Accept-Language) y conserva su elección; FlushPendingRegistrations envía a Langsys las frases recién descubiertas después de que se envía la respuesta, de modo que el registro nunca ralentiza una página.

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

Traducir en Blade

Una sola directiva: @t(phrase, category?, params?, locale?). Los parámetros se interpolan con marcadores {name}; los números y las fechas se muestran con el formato de la configuración regional, y la salida se escapa como HTML.

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

En cualquier parte de PHP

@t es simplemente el helper t() con escape; el helper en sí funciona en cualquier lugar: controladores, componentes Livewire, jobs, correos, mensajes de validación.

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

Plurales

Escribe la oración sin variantes: Langsys genera las formas plurales de cada configuración regional durante la traducción (incluida la configuración regional base) y el SDK renderiza la rama que coincide con tu cantidad (ICU completo mediante ext-intl). Es igual en todos los SDK, por lo que las frases son portables entre tu backend y tu 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]);

Las formas plurales que genera Langsys llegan a PHP desde langsys/langsys-php 1.3.2; las versiones anteriores muestran la forma plural para cualquier cantidad, incluido el 1.

Concordancia de género

El español, el francés o el ruso flexionan {username} has been invited según la persona a la que se refiere. Langsys genera esas ramas durante la traducción, igual que genera los plurales, y el argumento lleva el nombre de la variable con _gender al final: male, female u other. Pásalo siempre que lo sepas. Cómo funciona y cómo encontrar las frases que lo necesitan →

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

¿No sabes el género? Pasa 'other' de forma explícita: es la rama neutra. Si de todos modos falta, el SDK base toma la rama other por ti (langsys/langsys-php 1.3.1 y posteriores, con o sin ext-intl), de modo que la oración se lea correctamente.

Categorías

La categoría delimita el alcance de una frase, por lo que las mismas palabras pueden traducirse de forma distinta según el contexto.

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

¿Cuál debo usar?

Regla práctica: Blade → @t · PHP → t() · intocable → no lo envuelvas.

Descubrimiento de tokens en el servidor

Si renderizas una frase que Langsys no ha visto, se pone en cola y se registra después de que termina la respuesta: el visitante ve de inmediato tu texto en el idioma base, y la frase aparece en tu panel lista para traducir. Esto requiere una clave de escritura; con una clave de solo lectura la cola se omite en silencio, que es justo lo que quieres en entornos que no deben modificar el catálogo.

Integración con los SDK de JS

¿Usas Inertia o una app híbrida? Entrega a los SDK de JS el catálogo que el servidor ya obtuvo, para que el cliente no lo vuelva a descargar: es el mismo traspaso de initialTranslations que describen las páginas del SDK de 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 fachada y el cliente sin procesar

La fachada Langsys replica t(), y Langsys::client() te entrega el cliente langsys/langsys-php subyacente para todo lo que va más allá de buscar frases: lectura del catálogo, control de caché y bloques de contenido.

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