מתרגם/ת

‫Translator API מאפשר למפתחים לבצע תרגום טקסט בצד הלקוח באמצעות מודלי AI מובנים ב-Chrome וב-Edge. הגישה הזו מייתרת את הצורך בשירותי תרגום מבוססי-ענן לתוכן זמני, מפחיתה עלויות ומשפרת את הפרטיות על ידי שמירת הנתונים במכשיר של המשתמש.

דרישות מוקדמות ודרישות סף

פלטפורמת ה-API וההיקף הגלובלי

• חובה: צריך לגשת ל-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).
• אחסון: לפחות 22GB פנויים בנפח הפרופיל.
• זיכרון/מעבד (CPU): זיכרון RAM בנפח 16GB ומעלה ו-4 ליבות מעבד או יותר.
• GPU: זיכרון VRAM בנפח 4GB ומעלה (חובה ל-Prompt API עם אודיו).
• רשת: נדרשת רק להורדה הראשונית של חבילות השפה או המודלים.

הטמעה ודוגמאות קוד

1. בדיקת הזמינות וניהול המודלים

העברת אפשרויות חובה: צריך להעביר את אובייקט אפשרויות ההגדרה הזהה שמכיל את sourceLanguage ו-targetLanguage גם אל Translator.availability(options) וגם אל Translator.create(options).

מעקב מומלץ אחרי ההתקדמות: כדאי להטמיע מעקב אחרי התקדמות ההורדה של המודל על ידי הוספת קריאה חוזרת (callback) מסוג 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. התרגום מתבצע

ה-API תומך גם בתשובות סטטיות וגם בתשובות בסטרימינג. תמיד צריך לכלול מעקב אחרי התקדמות ההורדה כשמפעילים את המתרגם.

תרגום רגיל:

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

שפות נתמכות

ה-API תומך במגוון רחב של קודי שפה מסוג 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).
}

אם ה-API של Translator לא נתמך או שבדיקות הזמינות מחזירות את הערך 'unavailable', צריך להשתמש ב-fallback.

האפשרויות המומלצות:

1. חלופה ל-API מרוחק: הפניית בקשת התרגום לנקודת קצה בשרת או ל-API מרוחק בענן (כמו Vertex AI Gemini API) כדי לספק את פונקציונליות התרגום.
2. הפחתה חיננית (graceful degradation): משביתים באופן חזותי את רכיבי הבקרה או הלחצנים של התרגום, ומציגים הערה ידידותית למשתמש הקצה (למשל, "Client-side translation is currently unsupported in this browser"). לא מאפשרים חריגות לא מטופלות.
3. חלופת Polyfill: אתם יכולים להשתמש ב-Polyfill שמתוחזק על ידי הקהילה, כמו built-in-ai-task-apis-polyfills או prompt-api-polyfill, כדי לדמות את ממשק ה-API באמצעות שירותים מרוחקים.

השלכות על הפרטיות והעלות: יכול להיות שה-polyfills האלה מעבירים בקשות לשרתים מרוחקים (כמו Gemini API בענן), אבל אפשר גם לעבד אותן באופן מקומי. עיבוד מרחוק מבטל לחלוטין את ההגנה על הפרטיות במכשיר של ממשקי ה-API המובנים של AI, ולעיתים קרובות כרוך בעלויות שימוש ב-API בצד השרת.