الوثائقحزمة JavaScript7 دقيقة قراءة

حزمة JavaScript

حزمة siyak-js ملف واحد، بلا اعتماديات، وكائن واحد في المتصفح وعلى الخادم. ESM وCommonJS، وNode 18 فأحدث، وأي أداة حزم.

npm install ./siyak-js-0.1.0.tgz — للمتصفح وNode وReact Native.

npm install ./siyak-js-0.1.0.tgz    # the file you just downloaded

import { init } from 'siyak-js';        // ESM
const { init } = require('siyak-js');    // CommonJS

الخيارات

apiKeystring: مطلوب. sk_live أو sk_test. تُفحص الصيغة محليًا قبل أن تُهدر أي طلب.
targetstring: مطلوب. وسم BCP-47 مثل ar وar-EG وhe. الوسم الخاطئ يُفشل كل طلب، لذا يُتحقق منه عند التهيئة.
sourcestring: اختياري. عند حذفه تُستخدم لغة المصدر المضبوطة على المشروع.
contextstring: افتراضي اختياري للمعنى، يُتجاوز في كل استدعاء. السياق لكل نص أفضل، فسياق عام يجعل كل النصوص في شاشة واحدة.
endpointstring: مطلوب. المضيف فقط، ويُضاف /v1 تلقائيًا؛ وانسخ العنوان المكتوب في شاشة مفاتيح API بمشروعك. لا تحمل الحزمة مضيفًا افتراضيًا عمدًا: فأي نطاقٍ بديل قد يسجّله أحدٌ لاحقًا، والمفتاح الذي يصل إليه مفتاحٌ مسرّب. وحدّده لخادمٍ محلي أو لنشرتك الخاصة.
cachefalse | {maxEntries, ttlMs}: قيمة false تحفظ الترجمات في الذاكرة فقط — وهذا ما تريده في SSR والاختبارات والصفحات التي لا تملكها. الافتراضي ألف مدخل وثلاثون يومًا.
debounceMsnumber: نافذة تجميع للطلبات الخلفية. الافتراضي 50 مللي ثانية. قلّلها إن كنت تستدعي flush() بنفسك على أي حال.
onError(e) => void: يصل هنا كل خطأ تبتلعه الحزمة: {code, message, status}.
fetchSiyakFetch: أدخل fetch مخصصًا — للاختبارات أو لبيئة بلا fetch عام.

الدوال

t(text, context?)string: متزامنة لا ترمي. الترجمة من الذاكرة أو نصّك مع طلب في الخلفية.
translate(text, context?)Promise<string>: تنتظر الشبكة، وعند أي خطأ تُجيب بنصّك الأصلي، فلا ترفض أبدًا.
preload()Promise<void>: طلب واحد يملأ الذاكرة بكل ما يعرفه المشروع.
flush()Promise<void>: ترسل ما في الطابور الآن وتنتهي عند فراغه. تُستخدم في Node والاختبارات وقبل لقطات الواجهة.
onReadyPromise<void>: تنتهي عندما يهدأ الطابور والشبكة. أعد قراءتها بعد كل دفعة استدعاءات، فهي جديدة في كل مرة.
clearCache()void: تحذف نصوص هذا الكائن من الذاكرة والتخزين.

المتصفح

main.js

const siyak = init({
  apiKey: import.meta.env.VITE_SIYAK_KEY,
  endpoint: import.meta.env.VITE_SIYAK_URL,
  target: 'ar',
});

// Paint instantly, then repaint once the batch lands.
const render = () => document.getElementById('app')!.replaceChildren(t('Continue'));
siyak.t('Continue');
await siyak.onReady;
render();

Node.js وسطر الأوامر

server.js

const siyak = init({
  apiKey: process.env.SIYAK_KEY,
  endpoint: process.env.SIYAK_URL,
  target: 'ar',
  cache: false,           // no localStorage on a server
});

// A server render cannot repaint, so await the work it queues.
siyak.t('Your order has shipped');
siyak.t('Track shipment', 'screen:checkout');
await siyak.flush();

res.send(page({ continue: siyak.t('Continue') }));   // warm now

Node 18+ يوفّر fetch عامًّا؛ والإصدارات الأقدم تمرّره عبر خيار fetch.
قائمة النطاقات حارسٌ لمفاتيح المتصفح. أمّا مفتاح الخادم فلا متصفح له ليُحرس؛ فلذلك يبقى في البيئة لا داخل الحزمة.
الخادم بلا مستخدم يعيد الرسم، فاستدعِ flush() قبل العرض — وإلا خرج النص الأصلي.

التجميع في فقرة

كل نص ناقص خلال debounceMs يخرج كطلب واحد إلى POST /v1/translate/batch على دفعات من عشرين. استدعاءان لـ t() بالنص والسياق نفسيهما طلب واحد. و402 أو 429 يوقفان الكائن بقية الجلسة: لا يجوز لتطبيق أن يُغرق الخدمة بسبب فاتورة، فتبقى النصوص بلغتها الأصلية.