Laravel langsys/langsys-php-laravel

ربط Laravel خفيف فوق langsys/langsys-php: توجيه Blade ‏@t، والدالة المساعدة t()، وبرمجية وسيطة للغة المحلية. العبارة في شيفرتك هي مفتاح البحث والنص الافتراضي للغة الأساسية في آنٍ واحد — بلا ملف مفاتيح وبلا خطوة استخراج. تتم الترجمة على الخادم، فتصل الصفحة مترجمة بالفعل.

هذه حزمة SDK للواجهة الخلفية، لذا لا يوجد ملعب تجريبي داخل المتصفح في هذه الصفحة — فالمتصفح لا يستطيع تشغيل 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

ليس لديك مشروع أو مفاتيح بعد؟ يوفّر لك البدء السريع كليهما في دقيقتين.

البرمجية الوسيطة

تتولى برمجيتان وسيطتان العمل الخاص بإطار العمل: تحدد 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 اعتبارًا من الإصدار 1.3.2 من langsys/langsys-php؛ أما الإصدارات الأقدم فتعرض صيغة الجمع لكل عدد، بما في ذلك 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() · ما لا يمكن تعديله ← لا تغلّفه.

اكتشاف الرموز (Tokens) على الخادم

إذا عرضتَ عبارة لم يرها 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