Translator and Language Detector APIs

1. Introduction

For now, see the explainer .

2. The translator API

// TODO FIX: workaround for https://github.com/speced/bikeshed/issues/3023
// partial interface AI {
//   readonly attribute AITranslatorFactory translator;
// };
[Exposed=(Window,Worker), SecureContext]
interface AITranslatorFactory {  Promise<AITranslator> create(AITranslatorCreateOptions options);  Promise<AIAvailability> availability(AITranslatorCreateCoreOptions options);
};
[Exposed=(Window,Worker), SecureContext]
interface AITranslator {  Promise<DOMString> translate(    DOMString input,    optional AITranslatorTranslateOptions options = {}
  );
  ReadableStream translateStreaming(    DOMString input,    optional AITranslatorTranslateOptions options = {}
  );
  readonly attribute DOMString sourceLanguage;  readonly attribute DOMString targetLanguage;
};
AITranslator includes AIDestroyable;dictionary AITranslatorCreateCoreOptions {  required DOMString sourceLanguage;  required DOMString targetLanguage;
};
dictionary AITranslatorCreateOptions : AITranslatorCreateCoreOptions {  AbortSignal signal;  AICreateMonitorCallback monitor;
};
dictionary AITranslatorTranslateOptions {  AbortSignal signal;
};

Every AI has a translator factory , an AITranslatorFactory object. Upon creation of the AI object, its translator factory must be set to a new AITranslatorFactory object created in the AI object’s relevant realm .

The translator getter steps are to return this ’s translator factory .

2.1. Creation

The


create(

options

)

method steps are:

If this ’s relevant global object is a Window whose associated Document is not fully active , then return a promise rejected with an " InvalidStateError " DOMException.
If options [" signal "] exists and is aborted , then return a promise rejected with options [" signal "]'s abort reason .
Validate and canonicalize translator options given options.
This can mutate options.
Return the result of creating an AI model object given this ’s relevant realm ,options, compute translator options availability , download the translation model , initialize the translation model , and create a translator object .

To validate and canonicalize translator options given an


AITranslatorCreateCoreOptions

options, perform the following steps. They mutate options in place to canonicalize language tags, and throw a


TypeError

if any are invalid.

Validate and canonicalize language tags given options and " sourceLanguage ".
Validate and canonicalize language tags given options and " targetLanguage ".

To download the translation model , given an


AITranslatorCreateCoreOptions

options:

Assert : these steps are running in parallel .
Initiate the download process for everything the user agent needs to translate text from options [" sourceLanguage "] to options [" targetLanguage "]. This could include both a base translation model and specific language arc material, or perhaps material for multiple language arcs if an intermediate language is used.
If the download process cannot be started for any reason, then return false.
Return true.

To initialize the translation model , given an


AITranslatorCreateCoreOptions

options:

Assert : these steps are running in parallel .
Perform any necessary initialization operations for the AI model backing the user agent’s capabilities for translating from options [" sourceLanguage "] to options [" targetLanguage "].
This could include loading the model into memory, or loading any fine-tunings necessary to support the specific options in question.
If initialization failed for any reason, then return false.
Return true.

To create a translator object , given a realm realm and an


AITranslatorCreateCoreOptions

options:

Assert : these steps are running on realm ’s surrounding agent ’s event loop .
Return a new AITranslator object, created in realm, with
source language
options [" sourceLanguage "]
target language
options [" targetLanguage "]

2.2. Availability

The


availability(

options

)

method steps are:

If this ’s relevant global object is a Window whose associated Document is not fully active , then return a promise rejected with an " InvalidStateError " DOMException.
Validate and canonicalize translator options given options.
Let promise be a new promise created in this ’s relevant realm .
In parallel :
1. Let availability be the result of computing translator options availability given options.
2. Queue a global task on the AI task source given this ’s relevant global object to perform the following steps:
  1. If availability is null, then reject promise with an " UnknownError " DOMException.
  2. Otherwise, resolve promise with availability.

To compute translator options availability given an


AITranslatorCreateCoreOptions

options, perform the following steps. They return either an


AIAvailability

value or null, and they mutate options in place to update language tags to their best-fit matches.

Assert : this algorithm is running in parallel .
Let availabilities be the user agent’s translator language arc availabilities .
If availabilities is null, then return null.
For each languageArc → availability in availabilities:
1. Let sourceLanguageBestFit be LookupMatchingLocaleByBestFit (« languageArc ’s source language », « options [" sourceLanguage "] »).
2. Let targetLanguageBestFit be LookupMatchingLocaleByBestFit (« languageArc ’s target language », « options [" targetLanguage "] »).
3. If sourceLanguageBestFit and targetLanguageBestFit are both not undefined, then:
  1. Set options [" sourceLanguage "] to sourceLanguageBestFit.[[locale]].
  2. Set options [" targetLanguage "] to targetLanguageBestFit.[[locale]].
  3. Return availability.
If ( options [" sourceLanguage "], options [" targetLanguage "]) can be fulfilled by the identity translation , then return " available ".
Such cases could also return " downloadable ", " downloading ", or " available " because of the above steps, if the user agent has specific entries in its translator language arc availabilities for the given language arc. However, the identity translation is always available, so this step ensures that we never return " unavailable " for such cases.
One language arc that can be fulfilled by the identity translation is ( "en-US","en-GB" ). It is conceivable that an implementation might support a specialized model for this translation, which would show up in the translator language arc availabilities .
On the other hand, it’s pretty unlikely that an implementation has any specialized model for the language arc (" en-x-asdf ", " en-x-xyzw "). In such a case, this step takes over, and later calls to the translate algorithm will use the identity translation.
Note that when this step takes over, options [" sourceLanguage "] and options [" targetLanguage "] are not modified, so if this algorithm is being called from create(), that means the resulting AITranslator object’s sourceLanguage and targetLanguage properties will return the original inputs, and not some canonicalized form.
Return " unavailable ".

A language arc is a tuple of two strings, a source language and a target language . Each item is a Unicode canonicalized locale identifier .

The translator language arc availabilities are given by the following steps. They return a map from language arcs to


AIAvailability

values, or null.

Assert : this algorithm is running in parallel .
If there is some error attempting to determine what language arcs the user agent supports translating text between, which the user agent believes to be transient (such that re-querying the translator language arc availabilities could stop producing such an error), then return null.
Return a map from language arcs to AIAvailability values, where each key is a language arc that the user agent supports translating text between, filled according to the following constraints:
- If the user agent supports translating text from the source language to the target language of the language arc without performing any downloading operations, then the map must contain an entry whose key is that language arc and whose value is " available ".
- If the user agent supports translating text from the source language to the target language of the language arc , but only after finishing a currently-ongoing download, then the map must contain an entry whose key is that language arc and whose value is " downloading ".
- If the user agent supports translating text from the source language to the target language of the language arc , but only after performing a not-currently ongoing download, then the map must contain an entry whose key is that language arc and whose value is " downloadable ".
- The keys must not include any language arcs that overlap with the other keys .

Let’s suppose that the user agent’s translator language arc availabilities are as follows:

(" en ", " zh-Hans ") → " available "
(" en ", " zh-Hant ") → " downloadable "

The use of LookupMatchingLocaleByBestFit means that availability() will probably give the following answers:

function a(sourceLanguage, targetLanguage) {  return ai.translator.availability({ sourceLanguage, targetLanguage }):}await a("en", "zh-Hans") === "available";await a("en", "zh-Hant") === "downloadable";await a("en", "zh") === "available";            // zh will best-fit to zh-Hansawait a("en", "zh-TW") === "downloadable";      // zh-TW will best-fit to zh-Hantawait a("en", "zh-HK") === "available";         // zh-HK will best-fit to zh-Hansawait a("en", "zh-CN") === "available";         // zh-CN will best-fit to zh-Hansawait a("en-US", "zh-Hant") === "downloadable"; // en-US will best-fit to enawait a("en-GB", "zh-Hant") === "downloadable"; // en-GB will best-fit to en// Even very unexpected subtags will best-fit to en or zh-Hansawait a("en-Braille-x-lolcat", "zh-Hant") === "downloadable";await a("en", "zh-BR-Kana") === "available";

A language arc arc overlaps with a set of language arcs otherArcs if the following steps return true:

Let sourceLanguages be the set composed of the source languages of each item in otherArcs.
If LookupMatchingLocaleByBestFit ( sourceLanguages, « arc ’s source language ») is not undefined, then return true.
Let targetLanguages be the set composed of the target languages of each item in otherArcs.
If LookupMatchingLocaleByBestFit ( targetLanguages, « arc ’s target language ») is not undefined, then return true.
Return false.

The language arc ("

en

", "

fr

") overlaps with « ("

en

", "


fr-CA

") », so the user agent’s translator language arc availabilities cannot contain both of these language arcs at the same time.

Instead, a typical user agent will either support only one English-to-French language arc (presumably (" en ", " fr ")), or it could support multiple non-overlapping English-to-French language arcs, such as (" en ", " fr-FR "), (" en ", " fr-CA "), and (" en ", " fr-CH ").

In the latter case, if the web developer requested to create a translator using ai . translator . create ({ sourceLanguage : "en" , targetLanguage : "fr" }), the LookupMatchingLocaleByBestFit algorithm would choose one of the three possible language arcs to use (presumably (" en ", " fr-FR ")).

A language arc arc can be fulfilled by the identity translation if the following steps return true:

If LookupMatchingLocaleByBestFit (« arc ’s source language », « arc ’s target language ») is not undefined, then return true.
If LookupMatchingLocaleByBestFit (« arc ’s target language », « arc ’s source language ») is not undefined, then return true.
Return false.

2.3. The `AITranslator` class

Every AITranslator has a source language , a string , set during creation.

Every AITranslator has a target language , a string , set during creation.

The sourceLanguage getter steps are to return this ’s source language .

The targetLanguage getter steps are to return this ’s target language .

The


translate(

input
,
options

)

method steps are:

Let operation be an algorithm step which takes arguments chunkProduced,done,error, and stopProducing, and translates input given this ’s source language , this ’s target language ,chunkProduced,done,error, and stopProducing.
Return the result of getting an aggregated AI model result given this ,options, and operation.

The


translateStreaming(

input
,
options

)

method steps are:

Let operation be an algorithm step which takes arguments chunkProduced,done,error, and stopProducing, and translates input given this ’s source language , this ’s target language ,chunkProduced,done,error, and stopProducing.
Return the result of getting a streaming AI model result given this ,options, and operation.

2.4. Translation

2.4.1. The algorithm

To translate given:

a string input,
a Unicode canonicalized locale identifier sourceLanguage,
a Unicode canonicalized locale identifier targetLanguage,
an algorithm chunkProduced that takes a string and returns nothing,
an algorithm done that takes no arguments and returns nothing,
an algorithm error that takes error information and returns nothing, and
an algorithm stopProducing that takes no arguments and returns a boolean,

perform the following steps:

Assert : this algorithm is running in parallel .
In an implementation-defined manner, subject to the following guidelines, begin the processs of translating input from sourceLanguage into targetLanguage.
If input is the empty string, or otherwise consists of no translatable content (e.g., only contains whitespace, or control characters), then the resulting translation should be input. In such cases, sourceLanguage and targetLanguage should be ignored.
If ( sourceLanguage,targetLanguage ) can be fulfilled by the identity translation , then the resulting translation should be input.
While true:
1. Wait for the next chunk of translated text to be produced, for the translation process to finish, or for the result of calling stopProducing to become true.
2. If such a chunk is successfully produced:
  1. Let it be represented as a string chunk.
  2. Perform chunkProduced given chunk.
3. Otherwise, if the translation process has finished:
  1. Perform done.
  2. Break .
4. Otherwise, if stopProducing returns true, then break .
5. Otherwise, if an error occurred during translation:
  1. Let the error be represented as error information errorInfo according to the guidance in § 2.4.2 Errors .
  2. Perform error given errorInfo.
  3. Break .

2.4.2. Errors

When translation fails, the following possible reasons may be surfaced to the web developer. This table lists the possible DOMException names and the cases in which an implementation should use them:

`DOMException` name	Scenarios
" `NotAllowedError` "	Translation is disabled by user choice or user agent policy.
" `NotReadableError` "	The translation output was filtered by the user agent, e.g., because it was detected to be harmful, inaccurate, or nonsensical.
" `QuotaExceededError` "	The input to be translated was too large for the user agent to handle.
" `UnknownError` "	All other scenarios, or if the user agent would prefer not to disclose the failure reason.

This table does not give the complete list of exceptions that can be surfaced by translator.translate() and translator.translateStreaming(). It only contains those which can come from the implementation-defined translate algorithm.

Translator and Language Detector APIs

Abstract

Status of this document

1. Introduction

2. The translator API

2.1. Creation

2.2. Availability

2.3. The `AITranslator` class

2.4. Translation

2.4.1. The algorithm

2.4.2. Errors

Index

Terms defined by this specification

Terms defined by reference

References

Normative References

IDL Index

Translator and Language Detector APIs

Abstract

Status of this document

1. Introduction

2. The translator API

2.1. Creation

2.2. Availability

2.3. The AITranslator class

2.4. Translation

2.4.1. The algorithm

2.4.2. Errors

Index

Terms defined by this specification

Terms defined by reference

References

Normative References

IDL Index

2.3. The `AITranslator` class