Laravel langsys/langsys-php-laravel

Cienka warstwa integracji Laravela nad langsys/langsys-php: dyrektywa Blade @t, helper t() oraz middleware ustawiający język. Fraza w Twoim kodzie jest jednocześnie kluczem wyszukiwania i domyślnym tekstem w języku bazowym — bez pliku kluczy i bez etapu ekstrakcji. Tłumaczenie odbywa się na serwerze, więc strona trafia do użytkownika już zlokalizowana.

To SDK backendowe, więc na tej stronie nie ma playgroundu w przeglądarce — przeglądarka nie uruchomi PHP. Aplikacja demo to działająca wersja każdego z poniższych przykładów: sklonuj ją i uruchom php artisan serve albo otwórz ją w Codespace — prawdziwym kontenerze PHP, który sam ją zainstaluje i uruchomi. Pełna dokumentacja pakietu, w tym automatyczne tłumaczenie stron i zasilanie Inertia, znajduje się w dokumentacji 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.

Instalacja

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

Nie masz jeszcze projektu ani kluczy? Szybki start zapewni Ci jedno i drugie w dwie minuty.

Middleware

Dwa elementy middleware wykonują pracę po stronie frameworka: DetectLocale ustala ustawienia regionalne odwiedzającego (parametr zapytania, cookie, sesja, a następnie Accept-Language) i zapamiętuje jego wybór; FlushPendingRegistrations wysyła nowo wykryte frazy do Langsys po wysłaniu odpowiedzi, więc rejestracja nigdy nie spowalnia strony.

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

Tłumaczenie w Blade

Jedna dyrektywa: @t(phrase, category?, params?, locale?). Parametry są interpolowane za pomocą znaczników {name} — liczby i daty są formatowane zgodnie z ustawieniami regionalnymi — a wynik jest zabezpieczany przed HTML (escape'owany).

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

Gdziekolwiek w PHP

@t to po prostu helper t() z escapowaniem — sam helper działa wszędzie: w kontrolerach, komponentach Livewire, zadaniach, wiadomościach e-mail i komunikatach walidacji.

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

Liczba mnoga

Zapisz zdanie w płaskiej postaci: Langsys generuje formy liczby mnogiej dla każdego języka podczas tłumaczenia — łącznie z językiem bazowym — a SDK renderuje gałąź pasującą do Twojej liczby (pełne ICU przez ext-intl). Tak samo działa każde SDK, więc frazy pozostają przenośne między backendem a frontendem.

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

Formy liczby mnogiej generowane przez Langsys trafiają do PHP od wersji 1.3.2 pakietu langsys/langsys-php; starsze wersje renderują formę liczby mnogiej dla każdej liczby, także dla 1.

Zgodność rodzaju gramatycznego

W hiszpańskim, francuskim czy rosyjskim {username} has been invited odmienia się w zależności od osoby, której dotyczy. Langsys generuje te warianty podczas tłumaczenia — tak samo jak liczbę mnogą — a argument ma nazwę zmiennej z dopiskiem _gender: male, female lub other. Przekaż go zawsze, gdy go znasz. Jak to działa i jak znaleźć frazy, które tego potrzebują →

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

Nie znasz płci? Przekaż jawnie 'other' — to wariant neutralny. Jeśli mimo to go zabraknie, podstawowy SDK automatycznie użyje wariantu other (langsys/langsys-php w wersji 1.3.1 i nowszych, z ext-intl lub bez), dzięki czemu zdanie nadal brzmi poprawnie.

Kategorie

Kategoria wyznacza zakres frazy, dzięki czemu te same słowa mogą być tłumaczone inaczej w różnych kontekstach.

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

Którego mam użyć?

Zasada ogólna: Blade → @t · PHP → t() · nietykalne → nie opakowuj.

Wykrywanie tokenów na serwerze

Gdy wyrenderujesz frazę, której Langsys jeszcze nie widział, trafia ona do kolejki, a po zakończeniu odpowiedzi zostaje zarejestrowana — odwiedzający od razu widzi tekst w języku bazowym, a fraza pojawia się w Twoim panelu gotowa do tłumaczenia. Wymaga to klucza write; przy kluczu tylko do odczytu kolejka jest po cichu pomijana, czyli dokładnie tak, jak trzeba w środowiskach, które nie powinny modyfikować katalogu.

Łączenie z SDK dla JS

Używasz Inertia lub aplikacji hybrydowej? Przekaż SDK JS katalog, który serwer już pobrał, aby klient nie pobierał go ponownie — to ten sam mechanizm przekazywania initialTranslations, który opisują strony SDK dla frontendu.

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

Fasada i surowy klient

Fasada Langsys odpowiada metodzie t(), a Langsys::client() zwraca klienta langsys/langsys-php, którego użyjesz do wszystkiego poza wyszukiwaniem fraz — odczytu katalogu, sterowania pamięcią podręczną i bloków treści.

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