Skip to content

Commit f0ca9b2

Browse files
captainbrossetmikehoffms
captainbrosset
and
mikehoffms
authored
New article "Detect languages with the Language Detector API" (#3736)
* Initial docs for Language Detector API * Fix link * Update microsoft-edge/web-platform/languagedetector-api.md * Updated image * Enhance Language Detector API documentation with additional context and clarity * Correct version * Move intro content into new sections * Apply suggestions from code review Co-authored-by: Michael Hoffman <45407486+mikehoffms@users.noreply.github.com> * Apply suggestions from code review Co-authored-by: Michael Hoffman <45407486+mikehoffms@users.noreply.github.com> * Update detected image for Language Detector API * Add new feedback issue * Bug template is ready --------- Co-authored-by: Michael Hoffman <45407486+mikehoffms@users.noreply.github.com>
1 parent b966585 commit f0ca9b2

File tree

5 files changed

+386
-3
lines changed

5 files changed

+386
-3
lines changed

‎microsoft-edge/toc.yml‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -114,6 +114,9 @@
114114

115115
- name: Translate text with the Translator API
116116
href: ./web-platform/translator-api.md
117+
118+
- name: Detect languages with the Language Detector API
119+
href: ./web-platform/languagedetector-api.md
117120
# /Experimental APIs for Microsoft Edge
118121
# =============================================================================
119122
# -----------------------------------------------------------------------------

‎microsoft-edge/web-platform/languagedetector-api-images/detected.png‎

56.6 KB
Loading

‎microsoft-edge/web-platform/languagedetector-api-images/flags-language-detector-api.png‎

30.3 KB
Loading

‎microsoft-edge/web-platform/languagedetector-api.md‎

Lines changed: 380 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,380 @@
1+
---
2+
title: Detect languages with the Language Detector API
3+
description: Detect the language of text by using a model that's built into Microsoft Edge, from JavaScript code in your website or browser extension.
4+
author: MSEdgeTeam
5+
ms.author: msedgedevrel
6+
ms.topic: article
7+
ms.service: microsoft-edge
8+
ms.date: 03/04/2026
9+
---
10+
# Detect languages with the Language Detector API
11+
12+
The Language Detector API is an experimental web API that allows you to detect the language of text by using a model that's built into Microsoft Edge, from JavaScript code in your website or browser extension.
13+
14+
**Detailed contents:**
15+
16+
* [Introduction](#introduction)
17+
* [Use the Language Detector API with the Translator API](#use-the-language-detector-api-with-the-translator-api)
18+
* [Availability of the Language Detector API](#availability-of-the-language-detector-api)
19+
* [Benefits of the Language Detector API](#benefits-of-the-language-detector-api)
20+
* [Alternatives to the Language Detector API](#alternatives-to-the-language-detector-api)
21+
* [Disclaimer](#disclaimer)
22+
* [Model availability](#model-availability)
23+
* [Enable the Language Detector API](#enable-the-language-detector-api)
24+
* [See a working example](#see-a-working-example)
25+
* [Use the Language Detector API](#use-the-language-detector-api)
26+
* [Check if the Language Detector API is enabled](#check-if-the-language-detector-api-is-enabled)
27+
* [Check if the model can be used (availability())](#check-if-the-model-can-be-used-availability)
28+
* [Create a new session (create())](#create-a-new-session-create)
29+
* [Monitor the progress of the model download (monitor)](#monitor-the-progress-of-the-model-download-monitor)
30+
* [Run the Language Detector API (detect())](#run-the-language-detector-api-detect)
31+
* [Understanding the confidence scores](#understanding-the-confidence-scores)
32+
* [Destroy a session (destroy())](#destroy-a-session-destroy)
33+
* [Destroy a session by calling destroy()](#destroy-a-session-by-calling-destroy)
34+
* [Destroy a session by using AbortController](#destroy-a-session-by-using-abortcontroller)
35+
* [Send feedback](#send-feedback)
36+
* [See also](#see-also)
37+
38+
39+
<!-- ====================================================================== -->
40+
## Introduction
41+
42+
For introductory information about the Language Detector API, see:
43+
* [Translator and Language Detector APIs](https://webmachinelearning.github.io/translation-api/)
44+
* [Explainer for the Translator and Language Detector APIs](https://github.com/webmachinelearning/translation-api)
45+
46+
47+
<!-- ====================================================================== -->
48+
## Use the Language Detector API with the Translator API
49+
50+
To facilitate translating user-provided text to another language, use the Language Detector API in conjunction with the Translator API.
51+
52+
To learn about the Translator API see: [Translate text with the Translator API](./translator-api.md).
53+
54+
55+
<!-- ====================================================================== -->
56+
## Availability of the Language Detector API
57+
58+
The Language Detector API is available as a developer preview in the Microsoft Edge Canary or Dev channels, starting with version 147.0.3897.0. To download a preview channel of Microsoft Edge (Beta, Dev, or Canary), go to [Become a Microsoft Edge Insider](https://www.microsoft.com/edge/download/insider).
59+
60+
61+
<!-- ====================================================================== -->
62+
## Benefits of the Language Detector API
63+
64+
The Language Detector API uses a language detection model that runs on the same device where the inputs to and outputs of the model are used (that is, locally). This approach has the following benefits compared to cloud-based solutions:
65+
66+
* **Reduced cost:** There's no cost associated with using a cloud language detection service.
67+
68+
* **Network independence:** Beyond the initial model download, there's no network latency when using this API to detect languages, and the API can also be used when the device is offline.
69+
70+
* **Improved privacy:** The data input into the model never leaves the device, and isn't collected to train other AI models.
71+
72+
The language detection model is downloaded the first time the API is used in Microsoft Edge, and is subsequently shared across all websites in the browser. The model is accessed via a straightforward web API that doesn't require knowledge of third-party frameworks, and doesn't require Artificial Intelligence (AI) or Machine Learning (ML) expertise.
73+
74+
75+
<!-- ====================================================================== -->
76+
## Alternatives to the Language Detector API
77+
78+
You can send network requests to cloud-based language detection services with more sophisticated capabilities; see [Azure AI Language documentation](/azure/ai-services/language-service/).
79+
80+
As an on-device alternative, the Prompt API serves more custom scenarios, with a small language model that's built into Microsoft Edge; see [Prompt a built-in language model with the Prompt API](./prompt-api.md).
81+
82+
83+
<!-- ====================================================================== -->
84+
## Disclaimer
85+
86+
Like other machine learning models, the language detection model in Microsoft Edge can potentially produce results that are inaccurate or unreliable for certain inputs, such as short text or single words.
87+
88+
89+
<!-- ====================================================================== -->
90+
## Model availability
91+
92+
An initial download of the model is required the first time a website calls the Language Detector API. You can monitor the model download by using the monitor option when creating a new Language Detector API session; see [Monitor the progress of the model download (monitor)](#monitor-the-progress-of-the-model-download-monitor), below.
93+
94+
95+
<!-- ====================================================================== -->
96+
## Enable the Language Detector API
97+
98+
To use the Language Detector API in Microsoft Edge, set the flag, as follows:
99+
100+
1. In Microsoft Edge, go to `edge://version`, and make sure you're using version 147.0.3897.0 or later of Microsoft Edge, such as the Canary or Dev preview channel of Microsoft Edge.
101+
102+
To download a preview channel of Microsoft Edge (Beta, Dev, or Canary), go to [Become a Microsoft Edge Insider](https://www.microsoft.com/edge/download/insider).
103+
104+
1. In that version of Microsoft Edge, open a new tab or window and go to `edge://flags`.
105+
106+
1. In the **Search flags** text box at the top, start typing **Language detection web platform API**:
107+
108+
![Flags page of browser](./languagedetector-api-images/flags-language-detector-api.png)
109+
110+
The following flag is listed:
111+
112+
* **Language detection web platform API**
113+
114+
This entry shows `#edge-language-detection-api` (which links to `edge://flags/#edge-language-detection-api`).
115+
116+
1. Under **Language detection web platform API**, select **Enabled**.
117+
118+
In the lower right, a **Restart** button is displayed.
119+
120+
1. Click the **Restart** button.
121+
122+
123+
<!-- ====================================================================== -->
124+
## See a working example
125+
126+
To see the Language Detector API in action, and view existing code that uses this API:
127+
128+
1. [Enable the Language Detector API](#enable-the-language-detector-api), as described above.
129+
130+
1. In Microsoft Edge Canary or Dev, go to the [Language Detector API playground](https://microsoftedge.github.io/Demos/built-in-ai/playgrounds/languagedetector-api/) in a new window or tab.
131+
132+
1. In the information banner at the top, check the status: it initially reads: **On-device API and model available.**
133+
134+
1. In the **Text to analyze** text box, you can optionally change the text.
135+
136+
1. Click the **Detect language** button.
137+
138+
The model starts detecting the language of the text.
139+
140+
The output is generated in the response section of the page.
141+
142+
The output displays:
143+
* The name of the detected language.
144+
* The percent certainty of which language.
145+
146+
![The Language Detector demo page with settings and a Detect button](./languagedetector-api-images/detected.png)
147+
148+
See also:
149+
* [/built-in-ai/](https://github.com/MicrosoftEdge/Demos/tree/main/built-in-ai/) - Source code and Readme for the Built-in AI playgrounds demo.
150+
151+
152+
<!-- ====================================================================== -->
153+
## Use the Language Detector API
154+
155+
The next sections are about using the Language Detector API.
156+
157+
158+
<!-- ====================================================================== -->
159+
## Check if the Language Detector API is enabled
160+
161+
Before using the Language Detector API in your website's code, check that the API is enabled, by testing for the presence of the `LanguageDetector` object:
162+
163+
```javascript
164+
if (!LanguageDetector) {
165+
// The Language Detector API is not available.
166+
} else {
167+
// The Language Detector API is available.
168+
}
169+
```
170+
171+
172+
<!-- ====================================================================== -->
173+
## Check if the model can be used (`availability()`)
174+
175+
The Language Detector API can be used if the model and model runtime have been downloaded by Microsoft Edge.
176+
177+
To check if the API can be used, call `availability()`:
178+
179+
```javascript
180+
const availability = await LanguageDetector.availability();
181+
182+
if (availability == "unavailable") {
183+
// The model is not available.
184+
}
185+
186+
if (availability == "downloadable" || availability == "downloading") {
187+
// The model can be used, but it needs to be downloaded first.
188+
}
189+
190+
if (availability == "available") {
191+
// The model is available and can be used.
192+
}
193+
```
194+
195+
196+
<!-- ====================================================================== -->
197+
## Create a new session (`create()`)
198+
199+
Creating a session instructs the browser to load the language detection model in memory, so that the model can be used. Before you can detect the language, create a new session by using the `create()` method:
200+
201+
```javascript
202+
// Create a Language Detector session.
203+
const session = await LanguageDetector.create();
204+
```
205+
206+
To customize the model session, you can pass options to the `create()` method:
207+
208+
```javascript
209+
// Create a Language Detector session with options.
210+
const session = await LanguageDetector.create({
211+
expectedInputLanguages: ["en", "es", "fr"]
212+
monitor: monitorProgress
213+
});
214+
```
215+
216+
The available options are:
217+
218+
| **Option** | **Description** |
219+
| --- | --- |
220+
| `expectedInputLanguages` | An array of language codes. If there are certain languages you need to be able to detect for your use case, include them in the `expectedInputLanguages` option. This allows Microsoft Edge to download additional resources, if necessary, for better accuracy. The language codes should be in BCP 47 format (for example, `"en"` for English, `"es"` for Spanish, or `"fr"` for French). |
221+
| `monitor` | A function that's used to monitor the progress of the model download. See [Monitor the progress of the model download (monitor)](#monitor-the-progress-of-the-model-download-monitor), below. |
222+
223+
224+
<!-- ====================================================================== -->
225+
## Monitor the progress of the model download (`monitor`)
226+
227+
You can follow the progress of the model download by using the `monitor` option. This is useful when the model has not yet been fully downloaded onto the device where it will be used, to inform users of your website that they should wait.
228+
229+
```javascript
230+
// Create a Language Detector session with the monitor option to monitor the
231+
// model download.
232+
const session = await LanguageDetector.create({
233+
monitor: m => {
234+
// Use the monitor object argument to add a listener for the
235+
// downloadprogress event.
236+
m.addEventListener("downloadprogress", event => {
237+
// The event is an object with the loaded and total properties.
238+
if (event.loaded == event.total) {
239+
// The model is fully downloaded.
240+
} else {
241+
// The model is still downloading.
242+
const percentageComplete = (event.loaded / event.total) * 100;
243+
}
244+
});
245+
}
246+
});
247+
```
248+
249+
250+
<!-- ====================================================================== -->
251+
## Run the Language Detector API (`detect()`)
252+
253+
After you have created a model session, you can detect the language of text. The Language Detector API provides the `detect()` method to detect languages:
254+
255+
```javascript
256+
// Create a Language Detector session.
257+
const session = await LanguageDetector.create();
258+
259+
// Detect the language of the text.
260+
const results = await session.detect(someUserText);
261+
262+
// Use the results.
263+
for (const result of results) {
264+
// Show the full list of potential languages with their likelihood, ranked
265+
// from most likely to least likely.
266+
console.log(result.detectedLanguage, result.confidence);
267+
}
268+
```
269+
270+
The `detect()` method returns a promise that resolves to an array of language detection results. Each result is an object with the following properties:
271+
272+
| **Property** | **Description** |
273+
| --- | --- |
274+
| `detectedLanguage` | The BCP 47 language tag of the detected language (for example, `"en"` for English, `"es"` for Spanish, or `"und"` for undetermined). |
275+
| `confidence` | A number between 0.0 and 1.0, indicating the confidence level of the detection. Higher values indicate higher confidence. |
276+
277+
The results are sorted by confidence in descending order, with the most likely language first. The last entry in the results array is always the _undetermined_ language (`"und"`). The `undetermined` member in the array represents the percent confidence that the text is not in any of the languages that the model knows.
278+
279+
280+
<!-- ====================================================================== -->
281+
## Understanding the confidence scores
282+
283+
The confidence scores that are returned by the Language Detector API have the following characteristics:
284+
285+
* **Range:** Each confidence score is a number between 0 (lowest confidence) and 1 (highest confidence), inclusive.
286+
287+
* **Sorted results:** The results are sorted from highest to lowest confidence.
288+
289+
* **Low-confidence filtering:** Languages that have very low confidence are automatically filtered out, to reduce noise. _Low confidence_ is typically less than 1%, or less confident than the "undetermined" category.
290+
291+
* **Sum of scores:** The sum of all confidence scores might be less than 1, because low-probability languages are omitted from the results.
292+
293+
294+
<!-- ====================================================================== -->
295+
## Destroy a session (`destroy()`)
296+
297+
After detecting languages, destroy the session. This lets the browser know that you don't need the language model anymore, so that the model can be unloaded from memory.
298+
299+
You can destroy a session in two different ways:
300+
* By using the `destroy()` method.
301+
* By using an `AbortController`.
302+
303+
Details are below.
304+
305+
306+
<!-- ------------------------------ -->
307+
#### Destroy a session by calling `destroy()`
308+
309+
To destroy a session by calling `destroy()` with a `LanguageDetector` session:
310+
311+
```javascript
312+
const session = await LanguageDetector.create();
313+
314+
// Later, destroy the session by using the destroy method.
315+
session.destroy();
316+
```
317+
318+
319+
<!-- ------------------------------ -->
320+
#### Destroy a session by using `AbortController`
321+
322+
To destroy a session by creating an `AbortController` object, create a `LanguageDetector` session, and then call `abort()`:
323+
324+
```javascript
325+
// Create an AbortController object.
326+
const controller = new AbortController();
327+
328+
// Create a Language Detector session and pass the
329+
// AbortController object by using the signal option.
330+
const session = await LanguageDetector.create({
331+
signal: controller.signal
332+
});
333+
334+
// Later, perhaps when the user interacts with the UI, destroy the session by
335+
// calling the abort() function of the AbortController object.
336+
controller.abort();
337+
```
338+
339+
340+
<!-- ====================================================================== -->
341+
## Send feedback
342+
343+
We're interested in learning about:
344+
* The range of scenarios for which you intend to use the Language Detector API.
345+
* Any issues you encounter with the API or language detection model.
346+
* Whether other task-specific, built-in APIs would be useful.
347+
348+
To send feedback about your scenarios and the tasks you want to achieve, add a comment to [the Language Detector API feedback issue](https://github.com/MicrosoftEdge/MSEdgeExplainers/issues/1274).
349+
350+
If you notice any issues when using the API instead, please [report it on the repo](https://github.com/MicrosoftEdge/MSEdgeExplainers/issues/new?template=languagedetector-api.md).
351+
352+
You can also contribute to the discussion about the design of the Language Detector API, at the [W3C Web Machine Learning Working Group repository](https://github.com/webmachinelearning/translation-api).
353+
354+
355+
<!-- ====================================================================== -->
356+
## See also
357+
<!-- all links in article -->
358+
359+
<!-- Local: -->
360+
* [Translate text with the Translator API](./translator-api.md)
361+
* [Prompt a built-in language model with the Prompt API](./prompt-api.md)
362+
* [Summarize, write, and rewrite text with the Writing Assistance APIs](./writing-assistance-apis.md)
363+
* [Correct grammar and spelling with the Proofreader API](./proofreader-api.md)
364+
365+
Get Microsoft Edge:
366+
* [Become a Microsoft Edge Insider](https://www.microsoft.com/edge/download/insider) - download a preview channel of Microsoft Edge (Beta, Dev, or Canary).
367+
368+
GitHub:
369+
* [webmachinelearning / translation-api](https://github.com/webmachinelearning/translation-api) repo.
370+
* [Explainer for the Translator and Language Detector APIs](https://github.com/webmachinelearning/translation-api/blob/main/README.md)
371+
* [Translator and Language Detector APIs](https://webmachinelearning.github.io/translation-api/)
372+
373+
Azure docs:
374+
* [Azure AI Language documentation](/azure/ai-services/language-service/)
375+
376+
Demos repo:
377+
* [Language Detector API playground](https://microsoftedge.github.io/Demos/built-in-ai/playgrounds/languagedetector-api/)
378+
* [/built-in-ai/](https://github.com/MicrosoftEdge/Demos/tree/main/built-in-ai/) - Source code and Readme for the Built-in AI playgrounds demo.
379+
380+
<!-- omitted Feedback section links b/c must describe how to use

0 commit comments

Comments
 (0)