مترجم

ویژگی‌های وب: مترجم

Translator API به توسعه‌دهندگان امکان می‌دهد بااستفاده از مدل‌های هوش مصنوعی داخلی در Chrome و Edge، ترجمه نوشتار را در سمت کارخواه انجام دهند. این رویکرد نیاز به سرویس‌های ترجمه مبتنی بر ابر را برای محتوای زودگذر ازبین می‌برد، هزینه‌ها را کاهش می‌دهد، و با نگه داشتن داده‌ها در دستگاه کاربر، حریم خصوصی را بهبود می‌بخشد.

پیش‌نیازها و الزامات

سطح API و حوزه جهانی

  • اجباری: دسترسی به Translator API منحصراً ازطریق میانای جهانی Translator (window.Translator / self.Translator).
  • از فضای نام منسوخ‌شده window.ai.translator استفاده نکنید یا آن را بررسی نکنید.

پشتیبانی مرورگر

  • Chrome: نسخه ۱۳۸ و بالاتر (فقط رایانه).
  • Edge: نسخه ۱۴۸ به بالا (فقط رایانه).
  • پشتیبانی نمی‌شود: تلفن همراه (Android/iOS)،‏ Firefox،‏ Safari.

الزامات سخت‌افزاری

برای اجرای Gemini Nano و مدل‌های مرتبط، سیستم به موارد زیر نیاز دارد:

  • سیستم‌عامل: Windows 10/11،‏ macOS 13+،‏ Linux، یا ChromeOS (Chromebook Plus).
  • فضای ذخیره‌سازی: حداقل ۲۲ گیگابایت فضای خالی در حجم نمایه.
  • حافظه/واحد پردازش مرکزی: ۱۶ گیگابایت یا بیشتر حافظه دسترسی تصادفی و ۴ هسته واحد پردازش مرکزی یا بیشتر.
  • GPU:‏ ۴ گیگابایت+ VRAM (برای Prompt API با صدا الزامی است).
  • شبکه: فقط برای بارگیری اولیه بسته‌ها/ مدل‌های زبان لازم است.

نمونه‌های کد و پیاده‌سازی

۱. درحال بررسی دردسترس بودن و مدیریت مدل

ارسال گزینه‌های اجباری: باید شیء گزینه‌های پیکربندی یکسان حاوی 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.');
}

۲. درحال اجرای ترجمه‌ها

این میانای برنامه‌سازی کاربردی از هر دو پاسخ جاری‌سازی و ایستا پشتیبانی می‌کند. همیشه هنگام نمونه‌سازی مترجم، پایش پیشرفت بارگیری را اضافه کنید.

ترجمه استاندارد:

// 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 Fallback: می‌توانید از شبیه‌سازهای مرورگر نگهداری‌شده توسط انجمن مانند built-in-ai-task-apis-polyfills یا prompt-api-polyfill برای شبیه‌سازی سطح میانای برنامه‌سازی کاربردی بااستفاده از سرویس‌های ازراه‌دور استفاده کنید.

پیامدهای حریم خصوصی و هزینه: این شبیه‌سازهای مرورگر احتمالاً درخواست‌ها را به سرورهای راه دور (مانند Gemini API ازطریق فضای ابری) پروکسی می‌کنند، هرچند پردازش محلی نیز یک گزینه است. پردازش ازراه‌دور تضمین‌های حریم خصوصی درون‌دستگاهی میاناهای برنامه‌سازی کاربردی «هوش مصنوعی داخلی» را کاملاً باطل می‌کند و اغلب هزینه‌های استفاده از میانای برنامه‌سازی کاربردی سمت سرور را به‌همراه دارد.