Vue langsys-js-vue

ربط خفيف لـ Vue 3 فوق langsys-js-typescript، مبني على composables تصل الإشارات الأساسية بـ shallowRef. العبارة في شيفرتك هي مفتاح البحث والقيمة الافتراضية للغة الأساسية في الوقت نفسه.

Add Langsys translation to this Vue app.

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

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

تهيئة

import { LangsysApp, createLocaleStore } from 'langsys-js-vue';

const locale = createLocaleStore('en-US');

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

قراءة الإشارات

هل تحتاج إلى قراءة مخزن اللغات المحلية، أو أي إشارة من SDK الأساسي مثل مخزن تشاركه خارج Vue، بشكل تفاعلي؟ تربطه useSignal(store) بـ shallowRef يستطيع Vue تتبّعه. (لا يحتاج Svelte إلى ما يعادلها: فالإشارات تستوفي عقد المخزن لديه بشكل أصيل.)

<script setup>
import { useSignal, useCurrentLocale } from 'langsys-js-vue';

// Vue tracks only its own refs — a base-SDK signal is invisible to it.
// useSignal(signal) bridges it into a shallowRef Vue can track.
const selected = useSignal(locale);   // your createLocaleStore(...)
const loaded = useCurrentLocale();    // shortcut for the loaded locale
</script>

<template>
  <footer>selected {{ selected }} · loaded {{ loaded }}</footer>
</template>

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

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

const t = useT();

<p>{{ t("Hello, {name}! You have {count} new messages.", "Greetings", {"name":"Sarah","count":3}) }}</p>

<script setup>
import { useT } from 'langsys-js-vue';
const t = useT();
const name = 'Sarah';
</script>

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

أيها أستخدم؟

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

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

شاهد مقاطع العرض التوضيحي لهذه العناصر الأساسية موجودة حاليًا في صفحة Svelte، فالواجهة متطابقة ولا يختلف سوى بناء الجملة: <Translate> (1:04) · <Phrase> (1:06) · <DontTranslate> (0:34).

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

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

<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 setup>
import { useT } from 'langsys-js-vue';
const props = defineProps({ user: Object });
const t = useT();
</script>

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

لا تعرف الجنس؟ مرّر 'other' صراحةً — فهو الفرع المحايد. وإن لم تمرّره فسيعتمد SDK الفرع other نيابةً عنك (langsys-js-typescript الإصدار 0.6.4 فما بعده)، فتبقى الجملة سليمة. حاليًا يرفض TypeScript القيمة username_gender داخل كائن معلمات مضمّن (الخطأ TS2353؛ والإصلاح قيد المراجعة). إلى أن يصدر، أنشئ كائن المعلمات أولًا ثم مرّر المتغير.

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

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

// Nuxt: the server plugin 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',
});