Laravel langsys/langsys-php-laravel

Uma camada fina do Laravel sobre langsys/langsys-php: a diretiva Blade @t, o helper t() e o middleware de localidade. A frase no seu código é, ao mesmo tempo, a chave de busca e o padrão no idioma base — sem arquivo de chaves e sem etapa de extração. A tradução acontece no servidor, então a página já chega localizada.

SDK de backend, então não há playground no navegador nesta página, pois o navegador não executa PHP. O app de demonstração é a versão ao vivo de cada exemplo abaixo: clone-o e rode php artisan serve, ou abra-o em um Codespace, um contêiner PHP de verdade que instala e serve o app para você. A referência completa do pacote, incluindo tradução automática de páginas e seeding do Inertia, está na documentação do SDK para 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

Ainda não tem projeto ou chaves? O Início rápido entrega os dois em dois minutos.

Middleware

Dois middlewares cuidam do trabalho do framework: o DetectLocale resolve a localidade do visitante (parâmetro de consulta, cookie, sessão e depois Accept-Language) e guarda a escolha dele; o FlushPendingRegistrations envia as frases recém-descobertas ao Langsys depois que a resposta é enviada, de modo que o registro nunca deixa uma página lenta.

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

Traduzir no Blade

Uma diretiva: @t(phrase, category?, params?, locale?). Os parâmetros são interpolados com marcadores {name} — números e datas saem formatados conforme o locale — e a saída tem o HTML escapado.

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

Em qualquer lugar do PHP

@t é apenas o helper t() com escape — o próprio helper funciona em qualquer lugar: controllers, componentes Livewire, jobs, e-mails, mensagens de validação.

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

Plurais

Escreva a frase de forma simples: o Langsys gera as formas de plural de cada localidade durante a tradução — inclusive a da localidade base — e o SDK renderiza a ramificação que corresponde à sua contagem (ICU completo via ext-intl). É igual em todos os SDKs, então as frases ficam portáveis entre o seu backend e o 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]);

As formas plurais que o Langsys gera chegam ao PHP a partir do langsys/langsys-php 1.3.2; versões anteriores renderizam a forma plural para qualquer quantidade, inclusive 1.

Concordância de gênero

Espanhol, francês ou russo flexionam {username} has been invited de acordo com a pessoa a quem se refere. O Langsys gera essas variantes durante a tradução — do mesmo jeito que gera os plurais — e o argumento recebe o nome da variável, com _gender no final: male, female ou other. Informe-o sempre que souber. Como funciona e como encontrar as frases que precisam dele →

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

Não sabe o gênero? Passe 'other' explicitamente — é a variação neutra. Se ela estiver ausente mesmo assim, o SDK base usa a variação other para você (langsys/langsys-php 1.3.1 e posteriores, com ou sem ext-intl), e a frase continua correta.

Categorias

A categoria delimita o escopo de uma frase, então as mesmas palavras podem ser traduzidas de forma diferente em contextos diferentes.

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

Qual devo usar?

Regra prática: Blade → @t · PHP → t() · intocável → não envolva.

Descoberta de tokens no servidor

Se você renderizar uma frase que o Langsys ainda não conhece, ela entra em uma fila e é registrada depois que a resposta termina: o visitante vê imediatamente o texto no idioma base, e a frase aparece no seu painel pronta para tradução. Isso exige uma chave de escrita; com uma chave somente leitura, a fila é ignorada silenciosamente, que é exatamente o que você quer em ambientes que não devem alterar o catálogo.

Integração com os SDKs de JS

Usa Inertia ou um app híbrido? Passe aos SDKs de JS o catálogo que o servidor já buscou, para que o cliente não o busque de novo — o mesmo repasse de initialTranslations descrito nas páginas do 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,
});

O facade e o cliente bruto

A facade Langsys espelha t(), e Langsys::client() entrega o cliente langsys/langsys-php subjacente para tudo além da busca de frases — leitura do catálogo, controle de cache, blocos de conteúdo.

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