Translator and Language Detector APIs
{{DefaultAPISidebar("Translator and Language Detector APIs")}} {{SeeCompatTable}} {{securecontext_header}}
The Translator and Language Detector APIs provide functionality to detect the language that text is written in, and to translate text into different languages, via a browser’s own internal AI model (which may differ between browsers).
Concepts and usage
Translating a body of text is a common task on today’s web. Typical use cases include:
- 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.
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.
AI is well-suited to facilitating language detection and translation. The 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 AI model. This is useful and efficient because the browser handles the service, rather than the developer having to rely on the user downloading AI models, or host or pay for a cloud-based translation service.
- Language detection is done via the
{{domxref("LanguageDetector")}}interface. ALanguageDetectorobject instance is created using the{{domxref("LanguageDetector.create_static", "LanguageDetector.create()")}}static method, then the{{domxref("LanguageDetector.detect", "detect()")}}instance method is passed the text string to detect the language for. - Translation is done via the
{{domxref("Translator")}}interface. ATranslatorobject instance is created using the{{domxref("Translator.create_static", "Translator.create()")}}static method, then the{{domxref("Translator.translate", "translate()")}}instance method is passed the text string to translate.
You can cancel a pending create(), detect(), or translate() operation using an {{domxref("AbortController")}} .
After a LanguageDetector or Translator instance has been created, you can release its assigned resources and stop any further activity by calling its {{domxref("LanguageDetector.destroy()")}} /{{domxref("Translator.destroy()")}} method. You are encouraged to do this after you’ve finished with the object as it can consume a lot of resources.
See Using the Translator and Language Detector APIs for a walkthrough of how to use the APIs.
Interfaces
{{domxref("LanguageDetector")}}{{Experimental_Inline}}- : Contains all the language detection functionality, including checking AI model availability, creating a new
LanguageDetectorinstance, using it to detect a language, and more.
- : Contains all the language detection functionality, including checking AI model availability, creating a new
{{domxref("Translator")}}{{Experimental_Inline}}- : Contains all the translation functionality, including checking AI model availability, creating a new
Translatorinstance, using it to create a translation, and more.
- : Contains all the translation functionality, including checking AI model availability, creating a new
HTTP headers
{{httpheader("Permissions-Policy")}}; the{{httpheader("Permissions-Policy/language-detector", "language-detector")}}directive- : Controls access to the language detection functionality. Where a policy specifically disallows its use, any attempts to call the
LanguageDetectormethods will fail with aNotAllowedError{{domxref("DOMException")}}.
- : Controls access to the language detection functionality. Where a policy specifically disallows its use, any attempts to call the
{{httpheader("Permissions-Policy")}}; the{{httpheader("Permissions-Policy/translator", "translator")}}directive- : Controls access to the translation functionality. Where a policy specifically disallows its use, any attempts to call the
Translatormethods will fail with aNotAllowedError{{domxref("DOMException")}}.
- : Controls access to the translation functionality. Where a policy specifically disallows its use, any attempts to call the
Security considerations
Creation of LanguageDetector and Translator objects requires that the user has recently interacted with the page (transient user activation is required).
Access to the API is also controlled via {{httpheader("Permissions-Policy/language-detector", "language-detector")}} and {{httpheader("Permissions-Policy/translator", "translator")}} {{httpheader("Permissions-Policy")}} directives.
Examples
For a full example, see Using the Translator and Language Detector APIs.
Specifications
{{Specifications}}
Browser compatibility
{{Compat}}