Editorial review: Document Translator and Language Detector APIs #39457
Conversation
chrisdavidmills
requested review from
hamishwillee,
wbamberg and
bsmth
and removed request for
a team
chrisdavidmills
changed the title
Preview URLs (23 pages)
Flaws (28)Note! 2 documents with no flaws that don't need to be listed. 🎉 URL:
URL:
URL:
URL:
URL:
URL:
URL:
URL:
URL:
URL:
URL:
URL:
URL:
URL:
URL:
URL:
URL:
URL:
URL:
URL:
URL:
External URLs (18)URL:
URL:
URL:
URL:
URL:
URL:
URL:
URL:
URL:
URL:
(comment last updated: 2025-05-13 10:17:25) |
| "Translator and Language Detector APIs": { | ||
| "overview": ["Translator and Language Detector APIs"], | ||
| "guides": ["/docs/Web/API/Translator_and_Language_Detector_APIs/Using"], | ||
| "interfaces": ["CreateMonitor", "LanguageDetector", "Translator"], |
There was a problem hiding this comment.
Redlink in sidebar for this
There was a problem hiding this comment.
Yup, CreateMonitor is actually documented in the Summarizer API docs: #39263. It is shared functionality across all of these Google AI APIs.
|
|
||
| All of the language detection functionality is accessed through a single interface — {{domxref("LanguageDetector")}}. | ||
|
|
||
| The first step in getting the browser LLM to detect a language is to create a `LanguageDetector` object instance. This is done using the {{domxref("LanguageDetector.create_static", "LanguageDetector.create()")}} static method, which takes an options object as an argument: |
There was a problem hiding this comment.
The browser doesn't have to use LLM or even AI. Even if it does, might it not leverage an OS AI?
| The first step in getting the browser LLM to detect a language is to create a `LanguageDetector` object instance. This is done using the {{domxref("LanguageDetector.create_static", "LanguageDetector.create()")}} static method, which takes an options object as an argument: | |
| The first step in getting the browser to detect a language is to create a `LanguageDetector` object instance. This is done using the {{domxref("LanguageDetector.create_static", "LanguageDetector.create()")}} static method, which takes an options object as an argument: |
There was a problem hiding this comment.
I'm pretty sure it is supposed to be a browser AI model, but it is not necessarily an LLM. I've changed all of these to "AI model", as that's what I agreed upon with the tech reviewer in the Summarizer API PR.
|
|
||
| {{DefaultAPISidebar("Translator and Language Detector APIs")}} | ||
|
|
||
| The [Translator and Language Detector APIs](/en-US/docs/Web/API/Translator_and_Language_Detector_APIs) provide asynchronous ({{jsxref("Promise")}}-based) mechanisms for a website to detect languages and translate text via the browser's own internal language model. This is useful and efficient because the browser handles the service, rather than the developer having to rely on the user downloading large language models, or host or pay for a cloud-based translation service. This article explains how to use the fundamentals of the these APIs. |
There was a problem hiding this comment.
Does it have to be the browser model? I.e. can the browser leverage the OS?
There was a problem hiding this comment.
I think it does have to be a browser model, yes.
| ```js | ||
| const detectorAvailability = await LanguageDetector.availability({ | ||
| expectedInputLanguages: ["en-US", "ja"], | ||
| }); |
There was a problem hiding this comment.
It would be good to show the expected result of a console log.
- Are the results the same for each? I'd expect the former to return an array, but it might not.
There was a problem hiding this comment.
In each case, the returned result is an enum, which I state clearly below it, including the possible values. I've not included a console log result for each snippet because the result will vary across different browsers and implementations.
| }); | ||
| ``` | ||
|
|
||
| These methods return an emumerated value indicating whether support is, or will be available for the specified set of options. The meaning of the `available` and `unavailable` values is fairly obvious, but there are also `downloadable` and `downloading` values that mean support for the specified set of options is available to download or currently downloading, respectively. |
There was a problem hiding this comment.
- Are those four the only options?
- If I get "downloadable", how do I download?
- If I get "downloading", what do I do next?
There was a problem hiding this comment.
Ah, I think that the downloads happen when you create the translator/detector. Forward link to Monitoring download progress and usage
There was a problem hiding this comment.
It would be good to make this clear, yes! I've added the following paragraph below the list of options:
If a download is required, it will be started automatically by the browser once a
LanguageDetectororTranslatorinstance is created using the relevantcreate()method. You can track download progress automatically using a monitor.
| controller.abort(); | ||
| ``` | ||
|
|
||
| EDITORIAL: I've tried this, and it doesn't seem to work. Am I missing something? |
There was a problem hiding this comment.
YOu might want to tag who you want to test this here as a comment. FWIW I love live examples, in particular in the API reference part to test this kind of thing.
There was a problem hiding this comment.
I've tested this again, and it now works, by the looks of things. Comment removed.
|
|
||
| EDITORIAL: I've tried this, and it doesn't seem to work. Am I missing something? | ||
|
|
||
| Once a `Translator` or `LanguageDetector` instance has been created, you can destroy it when it is finished with using the {{domxref("Translator.destroy()")}}/{{domxref("LanguageDetector.destroy()")}} methods: |
There was a problem hiding this comment.
It is odd to be offered an explicit destroy() - probably worth explaining that (presumably) the translator objects are heavyweight and it makes sense to destroy them if they are not going to be used. Is there any advice on this?
There was a problem hiding this comment.
I think that's basically it, yes. I've added the following paragraph below the code snippet:
It makes sense to destroy these objects if they are no longer going to be used, as they tie up significant resources in their handling.
|
|
||
| ## Monitoring download progress and usage | ||
|
|
||
| If the AI model for a particular detection or translation is downloading (`availability()` returns `downloadable` and `downloading`), it is helpful to provide the user with feedback to tell them how long they need to wait before the operation completes. |
There was a problem hiding this comment.
- Does it have to be an AI model? COuld it be some other kind of model? I can see it is implied by the input quota, but any API might have a quota.
- OK, so I asked about downloading above https://github.com/mdn/content/pull/39457/files#r2083675830 - sounds like you just wait and if you're creating a translator it will complete once the thing is downloaded. Presumably if you start creating a translator specifying a downloadable translator model it will start downloading automatically?
There was a problem hiding this comment.
Questions answered above
| }); | ||
| ``` | ||
|
|
||
| It is also worth mentioning that AI APIs have an input quota that governs how many operations a website can request in a given period. The total quota can be accessed via the {{domxref("Translator.inputQuota")}}/{{domxref("LanguageDetector.inputQuota")}} properties, while the quota usage for a particular translation or language detection can be returned using the {{domxref("Translator.measureInputUsage()")}}/{{domxref("LanguageDetector.measureInputUsage()")}} methods: |
There was a problem hiding this comment.
| It is also worth mentioning that AI APIs have an input quota that governs how many operations a website can request in a given period. The total quota can be accessed via the {{domxref("Translator.inputQuota")}}/{{domxref("LanguageDetector.inputQuota")}} properties, while the quota usage for a particular translation or language detection can be returned using the {{domxref("Translator.measureInputUsage()")}}/{{domxref("LanguageDetector.measureInputUsage()")}} methods: | |
| It is also worth mentioning that some translation APIs have an input quota that governs how many operations a website can request in a given period. The total quota can be accessed via the {{domxref("Translator.inputQuota")}}/{{domxref("LanguageDetector.inputQuota")}} properties, while the quota usage for a particular translation or language detection can be returned using the {{domxref("Translator.measureInputUsage()")}}/{{domxref("LanguageDetector.measureInputUsage()")}} methods: |
There was a problem hiding this comment.
From my experience, at least so far, they all do, but it is possible that some implementations will not have (they'll just allow infinite operations, theoretically), and some future AI APIs might not use the same functionality. For better potential futureproofing, I've updated this line to
It is also worth mentioning that some implementations have an input quota...
|
|
||
| The rendered example looks like this: | ||
|
|
||
| {{EmbedLiveSample("translator-example", "100%", "400px")}} |
There was a problem hiding this comment.
What do I have to do to get this to work?
There was a problem hiding this comment.
Sorry, the BCD would have hopefully sorted you out on this, but we've not managed to get it published yet. I believe it will be enabled by default in Chrome 138, but for now you need to enable chrome://flags/#language-detection-api and chrome://flags/#translation-api
| Translating a body of text is a common task on today's web, and one that AI is well-suited to. Typical use cases include: | ||
|
|
||
| - An on-the-fly translation of an article that isn't available in your language. | ||
| - Translating a user's support requests into a language the support agent understands. | ||
| - Facilitating chats between users that don't speak each other's languages. | ||
|
|
||
| For successful automated translation, it is vital to be able to detect the language of a body of text, however, language detection also has other uses beyond translation. You could automatically switch the language of UI strings or error/feedback messages based on the text input by a user. You could also detect the language of entered text and then automatically load the correct dictionary for spell checking or curse word detection. |
There was a problem hiding this comment.
I know AI will be used for this, but it isn't a requirement of the API, and this kind of feels like it is purely about AI stuff.
The segue also felt a bit unwieldy. Maybe something like:
| Translating a body of text is a common task on today's web, and one that AI is well-suited to. Typical use cases include: | |
| - An on-the-fly translation of an article that isn't available in your language. | |
| - Translating a user's support requests into a language the support agent understands. | |
| - Facilitating chats between users that don't speak each other's languages. | |
| For successful automated translation, it is vital to be able to detect the language of a body of text, however, language detection also has other uses beyond translation. You could automatically switch the language of UI strings or error/feedback messages based on the text input by a user. You could also detect the language of entered text and then automatically load the correct dictionary for spell checking or curse word detection. | |
| Translating a body of text is a common task on today's web. | |
| Typical use cases include: | |
| - An on-the-fly translation of an article that isn't available in your language. | |
| - Translating support requests into language that a support agent (human or AI) understands. | |
| - Facilitating chats between users that don't speak each other's languages. | |
| Detecting the language of a body of test is an important precursor for successful automated translation, but has other uses beyond direct translation. | |
| For example, it allows automatic UI configuration based on user text entry, ranging from updating UI and error strings, to automatically loading appropriate dictionaries for spell checking or curse word detection. |
There was a problem hiding this comment.
I've used some of your language here, but really this is about AI, so I've kept that focus a bit. The spec says "These APIs are part of a family of APIs expected to be powered by machine learning models..."
I think AI should be the focus until we get solid proof that a browser is powering this API using a non-AI mechanism. And I'm not sure what that would look like.
I have given the "Using" and "Overview page" a quick scan. They look really clear, though a few questions. I would keep AI contribution perhaps to the main entry point and where it needs to be said. I'll try give it a proper go-over at the end of the week, |
@hamishwillee Ooops, sorry about that. I've updated them! |
Hrm, this looks like an alternative proposal. I'll see if the spec folks know what is going on here. |
@hamishwillee I'd wait until this has had a proper technical review. |
files/en-us/web/api/languagedetector/expectedinputlanguages/index.md
Outdated
Show resolved
Hide resolved
files/en-us/web/api/languagedetector/availability_static/index.md
Outdated
Show resolved
Hide resolved
Co-authored-by: Thomas Steiner <[email protected]>
Co-authored-by: Thomas Steiner <[email protected]>
Co-authored-by: Thomas Steiner <[email protected]>
Co-authored-by: Thomas Steiner <[email protected]>
Co-authored-by: Thomas Steiner <[email protected]>
Co-authored-by: Thomas Steiner <[email protected]>
Co-authored-by: Thomas Steiner <[email protected]>
chrisdavidmills
changed the title
|
OK, @hamishwillee, technical review done! You can get back to it ;-) |
Description
Chrome 138 supports the Translator and Language Detector APIs: see the relevant ChromeStatus entries: https://chromestatus.com/feature/6494349985841152 and https://chromestatus.com/feature/5172811302961152 .
This PR documents this set of APIs — I have done them as a single API, because they are so closely related. It would seem weird to me to have them on two separate API landing pages.
Specifically, I have added:
LanguageDetectorinterfaceTranslatorinterfacePermissions-PolicydirectivesNote that the
CreateMonitorinterface is shared functionality across multiple AI APIs; it is already documented in the Summarizer API PR — #39263.Motivation
Additional details
Related issues and pull requests