번역사

웹 기능: 번역 도구

Translator API를 사용하면 개발자가 Chrome 및 Edge의 내장 AI 모델을 사용하여 클라이언트 측 텍스트 번역을 실행할 수 있습니다. 이 접근 방식은 임시 콘텐츠에 대한 클라우드 기반 번역 서비스의 필요성을 없애고, 사용자 기기에 데이터를 보관하여 비용을 절감하고 개인 정보 보호를 개선합니다.

기본 요건 및 요구사항

API 노출 영역 및 전역 범위

  • 필수: 전역 Translator 인터페이스 (window.Translator / self.Translator)를 통해서만 Translator API에 액세스합니다.
  • 지원 중단된 window.ai.translator 네임스페이스를 사용하거나 확인하지 마세요.

브라우저 지원

  • Chrome: 버전 138 이상 (데스크톱만 해당)
  • Edge: 버전 148 이상 (데스크톱만 해당)
  • 지원되지 않음: 모바일 (Android/iOS), Firefox, Safari

하드웨어 요구사항

Gemini Nano 및 관련 모델을 실행하려면 시스템에 다음이 필요합니다.

  • 운영체제: Windows 10/11, macOS 13 이상, Linux 또는 ChromeOS (Chromebook Plus)
  • 저장용량: 프로필 볼륨에 최소 22GB의 여유 공간이 있어야 합니다.
  • 메모리/CPU: 16GB 이상의 RAM 및 4개 이상의 CPU 코어
  • GPU: 4GB 이상의 VRAM (오디오가 포함된 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 언어 코드를 지원합니다. 다음은 Chrome의 Translator API 구현에서 지원하는 언어입니다.

  • 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).
}

Translator API가 지원되지 않거나 사용 가능 여부 확인에서 '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)에 대한 요청을 프록시할 수 있지만 로컬 처리도 옵션입니다. 원격 처리는 네이티브 내장 AI API의 기기 내 개인 정보 보호 보장을 완전히 무효화하며 서버 측 API 사용 비용이 발생하는 경우가 많습니다.