Laravel langsys/langsys-php-laravel

langsys/langsys-php üzerine kurulu ince bir Laravel katmanı: @t Blade yönergesi, t() yardımcı fonksiyonu ve dil (locale) middleware'i. Kodunuzdaki ifade hem arama anahtarı hem de temel dildeki varsayılan metindir — anahtar dosyası yok, ayıklama adımı yok. Çeviri sunucuda yapılır, bu yüzden sayfa zaten yerelleştirilmiş olarak ulaşır.

Arka uç SDK'sı olduğu için bu sayfada tarayıcı içi deneme alanı yok; tarayıcı PHP çalıştıramaz. Demo uygulaması, aşağıdaki her örneğin canlı sürümüdür: klonlayıp php artisan serve komutunu çalıştırın ya da bir Codespace içinde açın; kurulumu ve sunumu sizin yerinize yapan gerçek bir PHP kapsayıcısıdır. Otomatik sayfa çevirisi ve Inertia tohumlaması dahil paketin tüm başvurusu Laravel SDK belgelerinde yer alır.

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.

Kurulum

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

Henüz projeniz veya anahtarlarınız yok mu? Hızlı başlangıç ikisini de iki dakikada sağlar.

Ara katman yazılımı

İki ara yazılım çerçeve işini üstlenir: DetectLocale ziyaretçinin dil ayarını belirler (sorgu parametresi, çerez, oturum, ardından Accept-Language) ve seçimini kalıcı hale getirir; FlushPendingRegistrations yeni keşfedilen ifadeleri yanıt gönderildikten sonra Langsys'e iletir, böylece kayıt işlemi sayfayı asla yavaşlatmaz.

// 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'de çeviri

Tek bir direktif: @t(phrase, category?, params?, locale?). Parametreler {name} işaretleyicileriyle eklenir; sayılar ve tarihler yerel ayara göre biçimlendirilir ve çıktı HTML-escape edilir.

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

PHP'nin her yerinde

@t, kaçış işlemi yapan t() yardımcısından ibarettir; yardımcının kendisi her yerde çalışır: controller'lar, Livewire bileşenleri, işler, e-postalar, doğrulama mesajları.

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

Çoğullar

Cümleyi düz yazın: Langsys, çeviri sırasında her yerel ayarın çoğul biçimlerini (temel yerel ayar dahil) oluşturur ve SDK, sayınıza uyan dalı işler (tam ICU desteği ext-intl ile). Her SDK'da aynıdır, bu yüzden ifadeler arka ucunuz ile ön ucunuz arasında taşınabilir kalır.

// 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'in oluşturduğu çoğul biçimleri PHP'ye langsys/langsys-php 1.3.2 sürümünden itibaren ulaşır; önceki sürümler, 1 dahil her sayı için çoğul biçimi kullanır.

Cinsiyet uyumu

İspanyolca, Fransızca veya Rusça {username} has been invited ifadesini, söz konusu kişiye göre çekimler. Langsys bu dalları çeviri sırasında, çoğulları oluşturduğu gibi oluşturur; argümanın adı değişkenin adına _gender eklenerek verilir: male, female veya other. Bildiğiniz her durumda iletin. Nasıl çalışır ve buna ihtiyaç duyan ifadeler nasıl bulunur →

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

Cinsiyeti bilmiyor musunuz? 'other' değerini açıkça iletin; bu, nötr daldır. Yine de eksikse temel SDK sizin yerinize other dalını kullanır (langsys/langsys-php 1.3.1 ve sonrası, ext-intl olsun ya da olmasın); böylece cümle yine doğru okunur.

Kategoriler

Kategori bir ifadenin kapsamını belirler; böylece aynı sözcükler farklı bağlamlarda farklı çevrilebilir.

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

Hangisini kullanmalıyım?

Pratik kural: Blade → @t · PHP → t() · dokunulmaz → sarmalamayın.

Sunucuda token keşfi

Langsys'in daha önce görmediği bir ifadeyi işlediğinizde ifade kuyruğa alınır, ardından yanıt sonlandıktan sonra kaydedilir; ziyaretçi hemen kaynak dildeki metninizi görür ve ifade çevrilmeye hazır şekilde kontrol panelinizde belirir. Bunun için bir yazma anahtarı gerekir; salt okunur bir anahtarda kuyruğa alma sessizce atlanır, bu da kataloğun değişmemesi gereken ortamlarda tam olarak istediğiniz davranıştır.

JS SDK'ları ile eşleştirme

Inertia veya hibrit bir uygulama mı çalıştırıyorsunuz? İstemci kataloğu yeniden çekmesin diye, sunucunun zaten çektiği kataloğu JS SDK'lara devredin — ön yüz SDK sayfalarında anlatılan initialTranslations aktarımının aynısı.

// 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 ve ham istemci

Langsys facade'ı t() işlevini yansıtır; Langsys::client() ise ifade aramanın ötesindeki her şey için — katalog okumaları, önbellek denetimi, içerik blokları — temeldeki langsys/langsys-php istemcisini size verir.

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