Svelte langsys-js-svelte

ربط Svelte 5 خفيف فوق langsys-js-typescript — الربط الأساسي الناضج. تستوفي الإشارات الأساسية أصلًا عقد المخزن في Svelte، لذا تُقرأ الترجمات بصيغة المخزن $.

Add Langsys translation to this Svelte app.

1. Read https://docs.langsys.dev/llms.txt, then follow
   https://docs.langsys.dev/learn/sdk/svelte/ 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.

التثبيت

npm install langsys-js-svelte

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

تهيئة

import { writable } from 'svelte/store';
import { LangsysApp } from 'langsys-js-svelte';

const locale = writable('en-US'); // a standard Svelte writable

await LangsysApp.init({
  projectid: import.meta.env.VITE_LANGSYS_PROJECT_ID,
  key: import.meta.env.VITE_LANGSYS_API_KEY, // read-only in the browser
  UserLocaleStore: locale,
});

ساحة تجريب تفاعلية

عدّل العبارة والفئة، واضبط المعلمات كحقول أو بصيغة JSON خام، ثم بدّل اللغة المحلية وشاهد SDK الفعلية تترجم مباشرةً.

const value = $derived($t("Hello, {name}! You have {count} new messages.", "Greetings", {"name":"Sarah","count":3}));

<script>
  import { t } from 'langsys-js-svelte';
  let name = 'Sarah';
</script>

<p>{$t('Hello, {name}!', 'Greetings', { name })}</p>

أيها أستخدم؟

قاعدة عامة: سلسلة نصية ← $t · جملة تحتوي على وسوم ← <Phrase> · منطقة من الوسوم ← <Translate> · ما لا يجوز المساس به ← <DontTranslate>.

يُعرض كل مكوّن محتوى مباشرةً على اليسار، والشيفرة التي تنتجه على اليمين، ومقطعه التجريبي فوق الاثنين.

<script>
  import { Translate } from 'langsys-js-svelte';
</script>

<Translate category="Home">
  <h3>Welcome to our store</h3>
  <p>Browse the catalog in your language.</p>
</Translate>

<Phrase category="Cart" params={{ name: 'Sarah', count: 3 }}>
  Hi %name%, you have %count% items in your cart.
</Phrase>

<!-- Inside a translated region, the marked span alone stays verbatim. -->
<Translate category="Tour">
  <p>Welcome! <DontTranslate>This sentence always stays in English.</DontTranslate> Thanks for visiting!</p>
</Translate>

التوافق في الجنس

تصرّف الإسبانية والفرنسية والروسية {username} has been invited بحسب الشخص المقصود. يولّد Langsys هذه الفروع أثناء الترجمة — بالطريقة نفسها التي يولّد بها صيغ الجمع — ويُسمّى الوسيط باسم المتغيّر مع إلحاق _gender به: male أو female أو other. مرّره متى كنت تعرفه. كيف يعمل ذلك، وكيف تعثر على العبارات التي تحتاج إليه ←

<script>
  import { t } from 'langsys-js-svelte';
  export let user; // user.gender is 'male' | 'female' | 'other'
</script>

<!-- Pass the agreement argument alongside the value it inflects. -->
<p>{$t('{username} has been invited', 'Team',
    { username: user.name, username_gender: user.gender })}</p>

لا تعرف الجنس؟ مرّر 'other' صراحةً — فهو الفرع المحايد. وإن كان مفقودًا، فستتولى الحزمة SDK اعتماد الفرع other نيابةً عنك (langsys-js-typescript الإصدار 0.6.4 فما فوق)، فتُقرأ الجملة بشكل صحيح.

كتل المحتوى

تُسجَّل منطقة <Translate> ككتلة محتوى واحدة: تُترجَم هذه الوحدة وتُراجَع كوحدة واحدة في مدير الترجمة، لكن كل مقطع نصي بداخلها يبقى عبارة مستقلة بذاتها. إذا كتبتَ الجملة نفسها في مكان آخر، فستعيد استخدام الترجمة الموجودة لها بالفعل.

<Translate category="Home">
    <h3>Welcome to our store</h3>
    <p>Browse the catalog in your language.</p>
    <p>Free shipping on orders over $50.</p>
</Translate>

الفئات

تجبرك مكتبات i18n الأخرى على ابتكار مفتاح لكل نص لأن الكلمة الواحدة قد تحمل معنيين. أما في Langsys فتبقى الجملة في شيفرتك البرمجية، وتتولى الفئة هذه المهمة: فالعبارة مع فئتها هي المفتاح، وبذلك تصبح الكلمة نفسها في فئتين ترجمتين مختلفتين.

<!-- The phrase plus its category is the key. -->
<a href="/">{$t('Home', 'Main menu')}</a>          <!-- es: Inicio -->
<h2>{$t('Home', 'Home repairs')}</h2>           <!-- es: Hogar -->

السمات

تكون ترجمة النموذج ناقصة إذا تغيّر النص الظاهر وبقي النص البديل للحقل ووصف الصورة وتسمية قارئ الشاشة بالإنجليزية. يصل <Translate> إلى كل ذلك في المرور نفسه: تُترجم placeholder وalt وtitle وaria-label وaria-placeholder مع النص، دون أي وسوم إضافية. وأي عنصر موسوم بـ translate="no" يُتجاهل، بما في ذلك العناصر الفرعية.

<Translate category="Checkout">
    <label>Email address</label>
    <input placeholder="[email protected]" />
    <img src="/lock.svg" alt="Secure checkout" />
    <button aria-label="Place your order">
        Place order
    </button>
</Translate>

الأرقام والتواريخ

مرّر الأرقام والتواريخ كمعاملات وسيقوم الـ SDK بتنسيقها وفق اللغة المعروضة، اعتماداً على CLDR (بيانات اللغات في Unicode): يمر الرقم عبر Intl.NumberFormat ويمر Date عبر Intl.DateTimeFormat. وهذا يشمل أكثر من الفاصل: فالتجميع نمط، لذا يظهر 1234567 بالشكل 1,234,567 في الإنجليزية الأمريكية وبالشكل 12,34,567 في الإنجليزية الهندية (en-IN).

الوجه الآخر: كل ما يُمرَّر على أنه رقم يُعامل ككمية. ورقم الطلب ليس كمية، لذا مرّره كسلسلة نصية، وإلا ستعرض الألمانية مرجع طلبك على هيئة 1.048.576.

<script lang="ts">
    import { t } from 'langsys-js-svelte';
    const renewsAt = new Date(2026, 2, 14); // 14 March 2026, local time
</script>

<p>{$t('Balance: {amount}', 'Billing', { amount: 1234.5 })}</p>
<p>{$t('Renews {when}', 'Billing', { when: renewsAt })}</p>

<!-- An order number is not a quantity: pass it as a string. -->
<p>{$t('Order {ref}', 'Billing', { ref: '1048576' })}</p>

العرض من جهة الخادم

اجلب الفهرس على الخادم (SvelteKit) وسلّمه إلى العميل، لتبدأ حزمة SDK دون جلبه مرة أخرى. تترجم الحزمة داخل المتصفح، لذا يبقى HTML المُنشأ على الخادم باللغة الأساسية إلى أن تبدأ.

// SvelteKit: +layout.server.ts seeds the catalog, the client init reuses it.
LangsysApp.init({
  projectid, key,
  UserLocaleStore: locale,
  initialTranslations,        // fetched on the server
  initialTranslationsLocale,  // fetched on the server
  ssrTokenStrategy: 'client',
});