Laravel langsys/langsys-php-laravel

Тонка прив’язка Laravel поверх langsys/langsys-php: директива Blade @t, хелпер t() та middleware для локалі. Фраза у вашому коді водночас є ключем пошуку і типовим значенням базової мови — без файлу ключів і без кроку вилучення. Переклад відбувається на сервері, тож сторінка приходить уже локалізованою.

Це серверний SDK, тому на цій сторінці немає playground у браузері — браузер не може виконувати PHP. Демозастосунок — це жива версія кожного з наведених нижче прикладів: клонуйте його та запустіть php artisan serve або відкрийте в Codespace — справжньому PHP-контейнері, який сам усе встановить і запустить. Повний довідник пакета, зокрема автоматичний переклад сторінок і початкове наповнення для Inertia, дивіться в документації 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.

Встановити

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

Ще немає проєкту чи ключів? Швидкий старт дасть вам і те, і інше за дві хвилини.

Middleware

Два middleware виконують роботу на рівні фреймворку: DetectLocale визначає локаль відвідувача (параметр запиту, кукі, сесія, потім Accept-Language) і зберігає його вибір; FlushPendingRegistrations надсилає нововиявлені фрази до Langsys після відправлення відповіді, тож реєстрація ніколи не уповільнює сторінку.

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

Переклад у Blade

Одна директива: @t(phrase, category?, params?, locale?). Параметри підставляються через маркери {name} — числа й дати виводяться з урахуванням локалі — а результат екранується як HTML.

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

Будь-де в PHP

@t — це просто допоміжна функція t() з екрануванням, а сама функція працює будь-де: у контролерах, компонентах Livewire, завданнях, листах, повідомленнях валідації.

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

Множина

Пишіть речення без розгалужень: Langsys генерує множинні форми для кожної локалі під час перекладу, враховуючи й базову локаль, а SDK відображає гілку, що відповідає вашому числу (повний ICU через ext-intl). У кожній SDK так само, тож фрази залишаються переносними між бекендом і фронтендом.

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

Множинні форми, які генерує Langsys, потрапляють до PHP із langsys/langsys-php версії 1.3.2; у попередніх версіях форма множини використовується для будь-якої кількості, зокрема й для 1.

Узгодження за родом

В іспанській, французькій чи російській мовах {username} has been invited змінюється залежно від особи, про яку йдеться. Langsys генерує ці гілки під час перекладу — так само, як і множинні форми — а аргумент називається за змінною з доданим _gender: male, female або other. Передавайте його щоразу, коли знаєте значення. Як це працює і як знайти фрази, яким це потрібно →

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

Не знаєте рід? Явно передайте 'other' — це нейтральна гілка. Якщо її все одно немає, базовий SDK сам візьме гілку other (langsys/langsys-php 1.3.1 і новіші, з ext-intl або без нього), тож речення все одно читатиметься правильно.

Категорії

Категорія задає область дії фрази, тож однакові слова можуть перекладатися по-різному в різних контекстах.

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

Який із них мені використовувати?

Практичне правило: Blade → @t · PHP → t() · недоторканне → не обгортайте.

Виявлення токенів на сервері

Якщо відобразити фразу, якої Langsys ще не бачив, вона потрапляє в чергу, а після завершення відповіді реєструється — відвідувач одразу бачить текст базовою мовою, а фраза з’являється у вашій панелі керування готовою до перекладу. Для цього потрібен ключ із правом запису; з ключем лише для читання черга непомітно пропускається, що саме те, що потрібно в середовищах, де каталог не повинен змінюватися.

Поєднання з JS SDK

Використовуєте Inertia або гібридний застосунок? Передайте JS SDK каталог, який сервер уже отримав, щоб клієнт не завантажував його повторно — це та сама передача initialTranslations, що описана на сторінках SDK для фронтенду.

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

Фасад і «сирий» клієнт

Фасад Langsys віддзеркалює t(), а Langsys::client() віддає вам базовий клієнт langsys/langsys-php для всього, що виходить за межі пошуку фраз, — читання каталогу, керування кешем, блоки контенту.

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