Tłumacz

Funkcje internetowe: Tłumacz

Interfejs Translator API umożliwia deweloperom tłumaczenie tekstu po stronie klienta za pomocą wbudowanych modeli AI w Chrome i Edge. Takie podejście eliminuje potrzebę korzystania z usług tłumaczeniowych działających w chmurze w przypadku treści efemerycznych, co zmniejsza koszty i poprawia prywatność, ponieważ dane są przechowywane na urządzeniu użytkownika.

Wymagania wstępne i wymagania

Interfejs API i zakres globalny

  • OBOWIĄZKOWO: uzyskuj dostęp do interfejsu Translator API wyłącznie przez globalny interfejs Translator (window.Translator / self.Translator).
  • NIE używaj ani nie sprawdzaj wycofanej przestrzeni nazw window.ai.translator.

Obsługa przeglądarek

  • Chrome: wersja 138 lub nowsza (tylko na komputerach).
  • Edge: wersja 148 lub nowsza (tylko na komputerach).
  • Nieobsługiwane: urządzenia mobilne (Android/iOS), Firefox, Safari.

Wymagania sprzętowe

Aby uruchomić Gemini Nano i powiązane modele, system potrzebuje:

  • System operacyjny: Windows 10/11, macOS 13 lub nowszy, Linux lub ChromeOS (Chromebook Plus).
  • Miejsce na dane: co najmniej 22 GB wolnego miejsca na woluminie profilu.
  • Pamięć/procesor: co najmniej 16 GB pamięci RAM i co najmniej 4 rdzenie procesora.
  • GPU: co najmniej 4 GB pamięci VRAM (wymagane w przypadku interfejsu Prompt API z dźwiękiem).
  • Sieć: wymagana tylko do początkowego pobrania pakietów językowych/modeli.

Implementacja i przykładowy kod

1. Sprawdzanie dostępności i zarządzanie modelami

Przekazywanie opcji obowiązkowych: musisz przekazać identyczny obiekt opcji konfiguracji zawierający sourceLanguage i targetLanguage do Translator.availability(options) i Translator.create(options).

Zalecane monitorowanie postępów: warto wdrożyć monitorowanie postępów pobierania modelu, podając wywołanie zwrotne monitor(m) do Translator.create() i dodając detektor zdarzenia downloadprogress, aby użytkownik mógł zobaczyć postęp pobierania modelu.

Wymaganie dotyczące gestu użytkownika: gdy wywołanie availability(options) zwraca 'downloadable' lub 'downloading', wywołanie Translator.create() powoduje pobranie pakietu językowego i bezwzględnie wymaga gestu użytkownika (np. kliknięcia przycisku), aby zapobiec wystąpieniu błędu NotAllowedError.

Funkcja Translator.availability(options) zwraca jeden z 4 stanów ciągu znaków:

  • 'available': model pary językowej został już pobrany na urządzenie i jest gotowy do natychmiastowego tłumaczenia.
  • 'downloadable': para językowa jest obsługiwana, ale model musi zostać pobrany. Do zainicjowania Translator.create() wymagany jest gest użytkownika.
  • 'downloading': pakiet językowy jest obecnie pobierany. Wywołanie Translator.create() za pomocą gestu użytkownika dołącza do pobierania.
  • 'unavailable': para językowa lub urządzenie nie są obsługiwane. Zastosuj strategię zastępczą.
// 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. Wykonywanie tłumaczeń

Interfejs API obsługuje zarówno odpowiedzi statyczne, jak i strumieniowe. Podczas tworzenia instancji translatora zawsze uwzględniaj monitorowanie postępu pobierania.

Tłumaczenie standardowe:

// 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 ?"

Tłumaczenie strumieniowe (w przypadku długiego tekstu):

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

Obsługiwane języki

Interfejs API obsługuje wiele kodów języków BCP 47. Oto języki obsługiwane przez implementację interfejsu Translator API w Chrome:

  • ar: arabski
  • bg: bułgarski
  • bn: bengalski
  • cs: czeski
  • da: duński
  • de: niemiecki
  • el: grecki
  • en: angielski
  • es: hiszpański
  • fi: fiński
  • fr: francuski
  • hi: hindi,
  • hr: chorwacki
  • hu: węgierski
  • id: indonezyjski
  • it: włoski
  • he: hebrajski
  • ja: japoński
  • kn: kannada
  • ko: koreański
  • lt: litewski
  • mr: marathi
  • nl: niderlandzki
  • no: norweski
  • pl: polski
  • pt: portugalski
  • ro: rumuński
  • ru: rosyjski
  • sk: słowacki
  • sl: słoweński
  • sv: szwedzki
  • ta: tamilski
  • te: telugu
  • th: tajski
  • tr: turecki
  • uk: ukraiński
  • vi: wietnamski
  • zh: chiński
  • zh-Hant: chiński (tradycyjny),

Bezpieczeństwo i wydajność

  • Zasady dotyczące uprawnień: elementy iframe typu cross-origin wymagają wyraźnego uprawnienia.

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

  • Skrypty Web Worker: obecnie nie są obsługiwane ze względu na złożoność zasad dotyczących uprawnień.

  • Prywatność: po pobraniu modelu podczas procesu tłumaczenia nie są wysyłane żadne dane na serwery Google.

Strategia zastępcza

Przed użyciem sprawdź, czy obiekt Translator jest dostępny w zakresie globalnym:

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

Jeśli interfejs API Translator nie jest obsługiwany lub testy dostępności zwracają wartość 'unavailable', musisz zastosować odpowiednie rozwiązanie zastępcze.

Zalecane opcje:

  1. Zastępczy zdalny interfejs API: przekieruj żądanie tłumaczenia do punktu końcowego serwera lub zdalnego interfejsu API w chmurze (takiego jak Vertex AI Gemini API), aby zapewnić funkcję tłumaczenia.
  2. Łagodna degradacja: wizualnie wyłącz elementy sterujące lub przyciski tłumaczenia, wyświetlając jednocześnie notatkę przyjazną dla użytkownika (np. "Client-side translation is currently unsupported in this browser"). Nie zezwalaj na nieobsługiwane wyjątki.
  3. Polyfill Fallback: możesz używać polyfilli utrzymywanych przez społeczność, takich jak built-in-ai-task-apis-polyfills lub prompt-api-polyfill, aby emulować interfejs API za pomocą usług zdalnych.

Prywatność i koszty: te polyfille mogą przekazywać żądania do serwerów zdalnych (np. Gemini API w chmurze), ale możliwe jest też przetwarzanie lokalne. Przetwarzanie zdalne całkowicie unieważnia gwarancje prywatności na urządzeniu, które zapewniają natywne wbudowane interfejsy AI API, i często wiąże się z kosztami korzystania z interfejsu API po stronie serwera.