Переводчик

Веб-функции: Переводчик

Translator API позволяет разработчикам выполнять клиентский перевод текста с помощью встроенных ИИ-моделей в Chrome и Edge. Этот подход устраняет необходимость в облачных сервисах перевода для временного контента, снижает затраты и повышает конфиденциальность за счет хранения данных на устройстве пользователя.

Предварительные условия и требования

API Surface и глобальная область действия

  • ОБЯЗАТЕЛЬНО. Доступ к 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 ГБ свободного места на диске, где хранится профиль.
  • Память/ЦП: не менее 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. Выполнение переводов

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>

  • Веб-воркеры. В настоящее время не поддерживаются из-за сложностей с правилами разрешений.

  • Конфиденциальность. После скачивания модели данные не отправляются на серверы 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', необходимо корректно вернуться к предыдущему состоянию.

Рекомендуемые варианты:

  1. Резервный удаленный API. Перенаправьте запрос на перевод в конечную точку сервера или облачный удаленный API (например, Vertex AI Gemini API), чтобы обеспечить работу функции перевода.
  2. Постепенное сокращение. Визуально отключите элементы управления переводом или кнопки, показывая при этом понятное конечному пользователю примечание (например, "Client-side translation is currently unsupported in this browser"). Не допускайте необработанных исключений.
  3. Резервный полифил. Вы можете использовать поддерживаемые сообществом полифилы, такие как built-in-ai-task-apis-polyfills или prompt-api-polyfill, чтобы эмулировать API с помощью удаленных сервисов.

Конфиденциальность и стоимость. Полифилы могут проксировать запросы к удаленным серверам (например, Gemini API в облаке), хотя локальная обработка также возможна. Удаленная обработка полностью аннулирует гарантии конфиденциальности на устройстве, которые предоставляют встроенные API ИИ, и часто приводит к расходам на использование API на стороне сервера.