Laravel langsys/langsys-php-laravel

Binding Laravel tipis di atas langsys/langsys-php: direktif Blade @t, helper t(), dan middleware locale. Frasa di kode Anda berfungsi sekaligus sebagai kunci pencarian dan default bahasa dasar — tanpa file kunci, tanpa langkah ekstraksi. Penerjemahan berlangsung di server, sehingga halaman tiba dalam kondisi sudah dilokalkan.

SDK backend, jadi tidak ada playground di browser pada halaman ini — browser tidak dapat menjalankan PHP. Aplikasi demo adalah versi langsung dari setiap contoh di bawah: kloning lalu jalankan php artisan serve, atau buka di Codespace — kontainer PHP sungguhan yang memasang dan menjalankannya untuk Anda. Referensi paket lengkap, termasuk terjemahan halaman otomatis dan seeding Inertia, tersedia di dokumentasi 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.

Instal

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

Belum punya proyek atau kunci? Mulai Cepat memberi Anda keduanya dalam dua menit.

Middleware

Dua middleware menangani tugas framework: DetectLocale menentukan lokal pengunjung (parameter query, cookie, sesi, lalu Accept-Language) dan menyimpan pilihan mereka; FlushPendingRegistrations mengirim frasa yang baru ditemukan ke Langsys setelah respons dikirim, sehingga pendaftaran tidak pernah memperlambat halaman.

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

Terjemahkan di Blade

Satu directive: @t(phrase, category?, params?, locale?). Parameter diinterpolasi dengan penanda {name} — angka dan tanggal ditampilkan dengan format sesuai locale — dan outputnya di-escape sebagai HTML.

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

Di mana saja dalam PHP

@t hanyalah helper t() dengan escaping — helper itu sendiri bisa dipakai di mana saja: controller, komponen Livewire, job, email, pesan validasi.

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

Bentuk jamak

Tulis kalimat apa adanya: Langsys menghasilkan bentuk jamak untuk setiap lokal selama penerjemahan — termasuk lokal dasar — dan SDK merender cabang yang sesuai dengan jumlah Anda (ICU lengkap melalui ext-intl). Sama di setiap SDK, sehingga frasa tetap portabel antara backend dan frontend Anda.

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

Bentuk jamak yang dihasilkan Langsys sampai ke PHP mulai dari langsys/langsys-php 1.3.2; versi sebelumnya merender bentuk jamak untuk setiap jumlah, termasuk 1.

Kesesuaian gender

Bahasa Spanyol, Prancis, atau Rusia memberi infleksi pada {username} has been invited sesuai orang yang dimaksud. Langsys menghasilkan cabang-cabang itu saat penerjemahan — dengan cara yang sama seperti menghasilkan bentuk jamak — dan argumennya dinamai sesuai variabelnya, dengan tambahan _gender: male, female, atau other. Berikan nilainya setiap kali Anda mengetahuinya. Cara kerjanya, dan cara menemukan frasa yang membutuhkannya →

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

Tidak tahu gendernya? Berikan 'other' secara eksplisit — itulah cabang netralnya. Jika tetap tidak ada, SDK dasar akan memakai cabang other untuk Anda (langsys/langsys-php 1.3.1 ke atas, dengan atau tanpa ext-intl), sehingga kalimat tetap terbaca dengan benar.

Kategori

Kategori membatasi cakupan sebuah frasa, sehingga kata yang sama dapat diterjemahkan secara berbeda dalam konteks yang berbeda.

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

Mana yang harus saya gunakan?

Aturan praktis: Blade → @t · PHP → t() · tidak boleh diubah → jangan dibungkus.

Penemuan token di server

Jika Anda merender frasa yang belum dikenal Langsys, frasa itu akan diantrekan, lalu didaftarkan setelah respons selesai — pengunjung langsung melihat teks bahasa dasar Anda, dan frasa tersebut muncul di dasbor Anda, siap diterjemahkan. Ini memerlukan kunci write; pada kunci hanya-baca, antrean dilewati secara diam-diam, yang memang diinginkan di lingkungan yang tidak boleh mengubah katalog.

Memasangkan dengan JS SDK

Menjalankan Inertia atau aplikasi hibrida? Berikan kepada SDK JS katalog yang sudah diambil server, sehingga klien tidak perlu mengambilnya lagi — serah terima initialTranslations yang sama seperti yang dijelaskan di halaman 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,
});

Facade & klien mentah

Facade Langsys meniru t(), dan Langsys::client() memberi Anda klien langsys/langsys-php di bawahnya untuk semua kebutuhan di luar pencarian frasa — pembacaan katalog, kontrol cache, blok konten.

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