This package detects when a page is translated on the client (using, for example, Google Translate in Chrome) or via a proxy (like using translate.google.com directly).
- Detects translation type:
client,proxy, orunknown - Detects translation service:
google,bing,yandex,baidu, etc - Reports the target language via the document
<html lang="...">attribute (plus heuristics for services that don’t set it reliably)
detect-translation can currently detect the following services:
- Baidu translate
- Google Translate
- Microsoft/Bing Translate
- Naver Papago
- Yandex Translate
- QQ Browser
- Sogou translate
- Youdao translate
pnpm add detect-translation
You can use npm or yarn if you prefer: npm i detect-translation, yarn add detect-translation
The package is written in TypeScript and ships its own types.
import { observe } from "detect-translation";
observe({
onTranslation: (lang, { service, type }) => {
// type: "proxy" | "client" | "unknown"
// service: e.g. "google", "bing", "yandex", "baidu" (see Services enum)
// lang: a BCP 47-ish language tag (e.g. "zh", "fr", "ru", "de", "hi", "es", "pt")
console.log(`${type} translation using ${service}, language ${lang}`);
},
sourceLang: "en",
});Ensure the script that calls observe runs after your HTML content is in the DOM.
lang is based on the <html> lang attribute (set by the translation service when possible), or identified heuristically if you provide a “Skip to main content” link (see below).
This package also ships a browser bundle that exposes a global DetectTranslation (useful for CDN usage).
<script src="https://unpkg.com/detect-translation@latest/dist-browser/index.min.js"></script>
<script>
DetectTranslation.observe({
sourceLang: "en",
onTranslation: function (lang, info) {
console.log(info.type, info.service, lang);
},
});
</script>If you use a bundler, prefer the module import shown in “Getting started”.
Some translation services do not identify the page language using standard lang attributes. To identify the language of translation in these cases, detect-translation uses heuristics based on known translations of a “canary” element on your pages.
By default, we use a hidden “Skip to main content” link, which is a common way of meeting a key accessibility requirement.
If you don’t already have a skip link on your pages, it’s easy to add. It’s best if it’s the first contentful element on the page:
<html lang="en">
<!-- or your page’s language, if not English -->
<body>
<a class="skip-link" href="#main-content">
Skip to main content
<!-- or the same phrase in your page’s language -->
</a>
<nav>
<!-- Add your navigation links here -->
</nav>
<main id="main-content">
<!-- your main page content goes here -->
</main>
</body>
</html>It’s usual to use CSS to hide this skip link until it receives keyboard focus. For details about styling hidden navigation links accessibly, see Carnegie Museums’ Web Accessibility Guidelines and How to Create a “Skip to Content” Link.
If you have a “Skip to main content” link on your page, provide a selector which detect-translation can use to find it:
import { observe } from "detect-translation";
observe({
onTranslation: (lang, { service, type }) => {
// type will be 'proxy', 'client' or 'unknown'
console.log(`${type} translation using ${service}, language ${lang}`);
},
sourceLang: "en", // or your page’s language, if different
sourceUrl: "https://www.mywebsite.com/path/to/page.html",
// no need to specify these if your skip link has a class of “.skip-link” and text
// “Skip to main content”
textSelector: ".skip-link", // a valid CSS selector passed to document.querySelector
text: "Skip to main content", // or the text in your page’s language
});textSelector and text default to ".skip-link" and "Skip to main content", respectively.
detect-translation can embed details of the translator in the language tags it passes to your callback, using the standard Transformed Content extension. For example, your callback can receive a language tag like zh-t-en-t0-baidu (using the BCP 47 T extension to indicate content in Chinese, translated from English by Baidu). This could be useful for analytics.
To enable this feature, just set includeTranslatorInLangTag to true in the options you pass to observe:
import { observe } from "detect-translation";
observe({
onTranslation: (lang, { service, type }) => {
// lang will be the BCP 47 code, for example zh, fr, ru, de, hi, es, pt etc
// type will be 'proxy', 'client' or 'unknown'
// service will be for example, 'google', 'bing', 'yandex', 'baidu' etc
console.log(`${type} translation using ${service}, language ${lang}`);
},
sourceLang: "en",
includeTranslatorInLangTag: true,
});A skip link is a common way of meeting a key accessibility requirement. It is a recommended technique to meet the WCAG 2.1 requirement 2.4.1 Bypass Blocks. Having this link before the navigation links on your pages allows users of assistive technology such as screenreaders to jump directly to your main content. See Deque University’s summary for more.
Then, if any translation service does not indicate the target language, we simply use the text of this element — which is translated along with your content — to identify the language.
It’s quite possible to use another phrase to identify translated content languages. Please just open an issue!
This repository uses pnpm.
Common commands:
pnpm install
pnpm test
pnpm run lint # biome
pnpm run knip # dead-code / unused deps
pnpm run build
pnpm run prepublish # the main verification gate (tests + lint + typecheck + knip + build + checks)Releases are tag-driven:
- Bump
package.jsonversion. - Create and push a tag like
v0.2.1.
GitHub Actions will run sanity checks and then publish to npm (requires the NPM_TOKEN repo secret), and create a GitHub Release with autogenerated notes.
MIT @ Claudiu Ceia