مترجم

ميزات الويب: المترجم

تتيح واجهة برمجة التطبيقات Translator API للمطوّرين ترجمة النصوص من جهة العميل باستخدام نماذج الذكاء الاصطناعي المضمّنة في Chrome وEdge. يغني هذا الأسلوب عن الحاجة إلى خدمات الترجمة المستندة إلى السحابة الإلكترونية للمحتوى المؤقت، ما يقلل التكاليف ويحسّن الخصوصية من خلال الاحتفاظ بالبيانات على جهاز المستخدم.

المتطلبات الأساسية والمتطلبات

واجهة برمجة التطبيقات والنطاق العالمي

  • إجراء إلزامي: يجب الوصول إلى Translator API حصريًا من خلال واجهة Translator العامة (window.Translator / self.Translator).
  • لا تستخدِم مساحة الاسم window.ai.translator التي تم إيقافها نهائيًا ولا تتحقّق منها.

المتصفّحات المتوافقة

  • ‫Chrome: الإصدار 138 والإصدارات الأحدث (على أجهزة الكمبيوتر فقط)
  • ‫Edge: الإصدار 148 والإصدارات الأحدث (على أجهزة الكمبيوتر فقط)
  • غير متوافق مع: الأجهزة الجوّالة (Android/iOS) وFirefox وSafari.

متطلبات الأجهزة

لتشغيل Gemini Nano والنماذج المرتبطة به، يحتاج النظام إلى ما يلي:

  • نظام التشغيل: Windows 10/11 أو macOS 13 أو إصدار أحدث أو Linux أو ChromeOS (Chromebook Plus)
  • مساحة التخزين: يجب توفّر مساحة لا تقل عن 22 غيغابايت في وحدة تخزين الملف الشخصي.
  • الذاكرة/وحدة المعالجة المركزية: ذاكرة وصول عشوائي (RAM) بسعة 16 غيغابايت أو أكثر و4 أنوية أو أكثر لوحدة المعالجة المركزية
  • وحدة معالجة الرسومات: ذاكرة وصول عشوائي للفيديو بسعة 4 غيغابايت أو أكثر (مطلوبة لاستخدام Prompt API مع الصوت)
  • الشبكة: مطلوبة فقط للتنزيل الأوّلي لحزم/نماذج اللغات.

التنفيذ وعيّنات التعليمات البرمجية

1. التحقّق من توفّر النماذج وإدارتها

تمرير الخيارات الإلزامية: يجب تمرير عنصر خيارات الإعداد المتطابق الذي يحتوي على sourceLanguage وtargetLanguage إلى كلّ من Translator.availability(options) وTranslator.create(options).

مراقبة مستوى التقدّم المقترَحة: يجب تنفيذ أداة لمراقبة مستوى تقدّم عملية تنزيل النموذج من خلال توفير دالة رد اتصال monitor(m) إلى Translator.create() وإضافة مستمع للحدث downloadprogress، ليتمكّن المستخدم من الاطّلاع على مستوى تقدّم عملية تنزيل النموذج.

متطلبات الإجراء التفاعلي من المستخدم: عند استدعاء availability(options)، يتم عرض 'downloadable' أو 'downloading'، ويؤدي استدعاء Translator.create() إلى تنزيل حزمة اللغة ويتطلب إجراءً تفاعليًا من المستخدم (مثل النقر على زر) لمنع حدوث NotAllowedError.

تعرض الدالة Translator.availability(options) إحدى حالات السلسلة الأربع التالية:

  • ‫'available': تم تنزيل نموذج زوج اللغات على الجهاز وهو جاهز للترجمة الفورية.
  • ‫'downloadable': زوج اللغات متوافق، ولكن يجب تنزيل النموذج. يجب تنفيذ إجراء تفاعلي من المستخدم لبدء Translator.create().
  • ‫'downloading': جارٍ تنزيل حزمة اللغة حاليًا. يؤدي استدعاء Translator.create() من خلال إجراء تفاعلي من المستخدم إلى إرفاق عملية التنزيل.
  • ‫'unavailable': زوج اللغات أو الجهاز غير متوافق. نفِّذ استراتيجية الاحتياط.
// Language pair options passed to both availability() and create()
const options = {
  sourceLanguage: 'es', // Example BCP 47 language code
  targetLanguage: 'fr', // Example BCP 47 language code
};

// 1. Check availability for the language pair
const availability = await Translator.availability(options);

if (availability === 'available') {
  // Model is ready immediately on device
  const translator = await Translator.create(options);
} else if (availability === 'downloadable' || availability === 'downloading') {
  // User gesture is strictly required before create() triggers or attaches to download
  document.getElementById('start-translation-btn').addEventListener('click', async () => {
    const translator = await Translator.create({
      ...options,
      monitor(m) {
        m.addEventListener('downloadprogress', (e) => {
          console.log(`Downloaded ${Math.round(e.loaded * 100)}%`);
        });
      },
    });
  });
} else if (availability === 'unavailable') {
  // Language pair or hardware unsupported; execute fallback
  console.warn('Translation model is unavailable on this device.');
}

2. تنفيذ الترجمات

تتيح واجهة برمجة التطبيقات الردود الثابتة وردود البث. يجب دائمًا تضمين مراقبة مستوى تقدّم عملية التنزيل عند إنشاء مثيل للمترجم.

الترجمة العادية:

// Default to including a progress monitor when creating translator
const translator = await Translator.create({
  sourceLanguage: 'en',
  targetLanguage: 'fr',
  monitor(m) {
    m.addEventListener('downloadprogress', (e) => {
      console.log(`Downloaded ${Math.round(e.loaded * 100)}%`);
    });
  },
});

const result = await translator.translate(
  'Where is the next bus stop, please?',
);
console.log(result);
// Output: "Où est le prochain arrêt de bus, s'il vous plaît ?"

الترجمة المباشرة (للنصوص الطويلة):

const stream = translator.translateStreaming(longText);
for await (const chunk of stream) {
  console.log(chunk);
}

اللغات المتاحة

تتيح واجهة برمجة التطبيقات مجموعة كبيرة من رموز لغات BCP 47: في ما يلي اللغات التي تتيحها واجهة برمجة التطبيقات Translator API في Chrome:

  • ar: العربية
  • bg: البلغارية
  • ‫bn: البنغالية
  • cs: التشيكية
  • ‫da: الدانمركية
  • de: الألمانية
  • el: اليونانية
  • en: الإنجليزية
  • es: الإسبانية
  • ‫fi: الفنلندية
  • fr: الفرنسية
  • hi: الهندية
  • hr: الكرواتية
  • ‫hu: الهنغارية
  • id: الإندونيسية
  • it: الإيطالية
  • he: العبرية
  • ja: اليابانية
  • kn: الكنادية
  • ko: الكورية
  • lt: الليتوانية
  • mr: الماراثية
  • nl: الهولندية
  • no: النرويجية
  • ‫pl: البولندية
  • pt: البرتغالية
  • ‫ro: الرومانية
  • ru: الروسية
  • sk: السلوفاكية
  • sl: السلوفينية
  • sv: السويدية
  • ta: التاميلية
  • te: التيلوغوية
  • th: التايلاندية
  • tr: التركية
  • ‫uk: الأوكرانية
  • vi: الفيتنامية
  • zh: الصينية
  • zh-Hant: الصينية (التقليدية)

الأمان والأداء

  • سياسة الأذونات: تتطلّب إطارات iframe المتعدّدة المصادر إذنًا صريحًا.

    <iframe src="https://example.com/" allow="translator"></iframe>

  • Web Workers: غير متاحة حاليًا بسبب تعقيدات "سياسة الأذونات".

  • الخصوصية: لا يتم إرسال أي بيانات إلى خوادم Google أثناء عملية الترجمة بعد تنزيل النموذج.

استراتيجية الإجراءات الاحتياطية

قبل الاستخدام، تحقَّق مما إذا كان العنصر Translator متاحًا في النطاق العام:

if ('Translator' in self) {
  // The Translator API is supported.
} else {
  // Execute fallback strategy (do not fall back to window.ai.translator).
}

إذا كانت واجهة برمجة التطبيقات Translator غير متاحة أو إذا عرضت عمليات التحقّق من التوفّر القيمة 'unavailable'، يجب الرجوع إلى الحالة السابقة بسلاسة.

الخيارات المقترَحة:

  1. الاستعانة بواجهة برمجة تطبيقات عن بُعد: يمكنك إعادة توجيه طلب الترجمة إلى نقطة نهاية خادم أو واجهة برمجة تطبيقات عن بُعد في السحابة الإلكترونية (مثل Vertex AI Gemini API) لتوفير وظيفة الترجمة.
  2. التكيّف مع الإصدارات الأقدم: يمكنك إيقاف عناصر التحكّم في الترجمة أو الأزرار بشكل مرئي مع عرض ملاحظة سهلة الاستخدام للمستخدم النهائي (مثل "Client-side translation is currently unsupported in this browser"). لا تسمح بالاستثناءات التي لم تتم معالجتها.
  3. الاحتياطي لـ Polyfill: يمكنك استخدام polyfills التي يديرها المنتدى، مثل built-in-ai-task-apis-polyfills أو prompt-api-polyfill، لمحاكاة واجهة برمجة التطبيقات باستخدام الخدمات عن بُعد.

الآثار المترتبة على الخصوصية والتكلفة: من المحتمل أن تنقل هذه الرموز الطلبات إلى خوادم عن بُعد (مثل Gemini API عبر السحابة الإلكترونية)، مع أنّ المعالجة المحلية هي خيار أيضًا. تؤدي المعالجة عن بُعد إلى إلغاء ضمانات الخصوصية على الجهاز فقط التي توفّرها واجهات برمجة التطبيقات المُدمَجة المستنِدة إلى الذكاء الاصطناعي، وغالبًا ما تؤدي إلى تحمُّل تكاليف استخدام واجهة برمجة التطبيقات من جهة الخادم.