# translate.js: automatic HTML translation with two script tags

> translate.js scans your rendered DOM and translates the text in place, with no language files and no API key. The README documents dozens of tuning hooks, and the package is MIT licensed, but the default client.edge channel is a dependency you do not control.

**xnx3/translate** — AI i18n, Two lines of js realize automatic html translation. No need to change the page, no language configuration file, no API key, SEO friendly!

- Repository: https://github.com/xnx3/translate
- Stars: 3,090 · Forks: 481
- Language: JavaScript
- License: MIT
- Published: 2026-09-24 · Updated: 2026-09-24 · Language: en
- Canonical page: https://hysenlabs.com/projects/xnx3-translate

## What translate.js replaces, and who ends up using it

The usual path to a multilingual site is a language file per locale, a key for every string, and a build step that swaps them. translate.js takes the opposite route. The README states that the script scans your DOM, identifies the text, and translates what it finds, so there is nothing to extract and nothing to keep in sync. The pitch is aimed at sites that already exist: a marketing page, a documentation site, an admin panel built in Vue or React, where adding a second locale would mean touching every template. The README also lists private deployment as a supported path for government or large-enterprise projects with data-confidentiality requirements or no external network access. That is a different audience from the weekend site owner who just wants a language dropdown, and it is the more demanding one, because it implies the translation API itself can be replaced.

## How the DOM scan works and where the text goes

The library does not sit between your templates and the browser. It runs after the page has rendered, walks the DOM, and collects the text nodes it should translate. The quick start shows four calls: set the local language, choose a translation channel, start the listener, then execute. The listener is what makes it work on JavaScript-heavy pages. According to the README, translate.listener.start() enables monitoring of page elements so that content changed by JavaScript is also translated, which is what makes it usable on Vue and React applications where the initial HTML is nearly empty. The README also describes three layers of cache, preloading, and text preprocessing, and it says the script does not modify the page source that crawlers receive. That last claim is the one worth checking on your own site, because it is the basis for the SEO-friendly claim, and it depends on the crawler executing JavaScript or not.

## Installing translate.js and getting a first translation

There is no package manager step in the README. The documented integration is a script tag pointing at a CDN build, placed before the closing html tag. The example below is copied from the quick start section, and it is the whole integration. After you paste it and reload, a language select appears near the bottom of the page, and choosing a language replaces the visible text.

```html
<script src="https://cdn.staticfile.net/translate.js/3.18.66/translate.js"></script>
<script>
translate.language.setLocal('chinese_simplified');
translate.service.use('client.edge');
translate.listener.start();
translate.execute();
</script>
```

The first line sets the source language. The README notes that if you skip translate.language.setLocal, the library auto-detects it by taking the most frequent language in the page text, which is a reasonable default and a bad one on a page with a long English code sample. The second line picks the translation channel; the README points to a separate page for the channel options and recommends a model-based channel for production. The third line starts DOM monitoring, and the fourth triggers the first pass. For a quick look without touching your own files, the README suggests opening any page, pasting a snippet into the browser console through the inspector, and pressing Enter, after which a large language switcher appears in the top-left corner.

## The tuning surface is the real product

Four calls get you a translated page. The README then lists roughly thirty configuration points, and that list is the honest measure of how much control you get. You can restrict translation to specific elements, exclude ids, classes, tags, or text patterns, define your own glossary for terms the machine gets wrong, translate image text, add a loading mask over elements while the API responds, hook into the API response, and rewrite the browser cache layer if localStorage is not what you want. There are also hooks for switching users automatically based on their language and country, reading the target language back at runtime, and controlling the language through a URL parameter. The breadth cuts both ways. A team with an unusual requirement will probably find a switch for it. A team without one now has thirty switches to read before it can be confident about what ships.

## Where translate.js is the wrong choice

Machine translation at render time is not the same as a translated site. Nothing in the README describes a review step, so a term that matters to your business can come back wrong and stay wrong until someone notices. There is no built-in versioning of translations, and the README does not document rollback; the closest thing is the cache-clearing call and the offline mode, which the README describes as the traditional i18n capability with a language file for results. If your content is legally reviewed, if a mistranslation carries a compliance cost, or if you need per-string approval before publication, this design works against you. The same applies to pages where text is embedded in canvas, SVG, or images that the DOM scan cannot reach as text nodes. And because the default channel is a remote service, an outage or a slow response shows up as untranslated or partially translated text, not as a page that fails to load.

## How it differs from a conventional i18n library

Libraries in the i18next and vue-i18n family work from keys. You write a key in the template, and the library looks up the string for the active locale from a file you maintain. That gives you a reviewable artifact, deterministic output, and no runtime dependency on a translation service. It also means every new string needs a new entry, and every locale needs a translator. translate.js inverts all of that: no keys, no files, no review, and a runtime call to a translation service. The README does mention an offline mode that generates a configuration file, which narrows the gap, but that is a bolt-on to the dynamic design rather than the core. The choice is between control over the output and control over the work.

## Licence, maintenance and upgrade cost

The repository is MIT licensed, and the README states the project is permanently free to use under that licence, including as a component of a commercial product or browser plugin. The repository is not archived, and the last push was on 2026-09-18. The most recent tagged release is v4.0.0 from 2026-02-10, following v3.18.98 and v3.18.89. The quick start snippet pins version 3.18.66 in the CDN path while package.json reports 4.1.0, so the version you copy from the README and the version in the repository are not the same; check which one you actually want before pasting. Upgrades are cheap in the sense that there is no schema and no locale files to migrate, and expensive in the sense that a CDN path change is a one-line edit that can alter behaviour on every page at once. Pin the version in the URL rather than tracking latest if you want predictable output.

## Conclusion

translate.js fits teams that need a multilingual page without touching templates or maintaining language files, and it is the wrong tool when every string must be reviewed before it ships. Before rollout, pick a service channel deliberately: the quick start uses translate.service.use('client.edge'), and the README points to a separate page for switching to a more stable model channel. Verify what your page looks like in the raw source before the script runs, since that is what the README says crawlers index.

## FAQ

### Does translate.js need an API key?

The README states that no key is required and that the project is open and ready to use. The quick start selects a channel with translate.service.use('client.edge') instead of supplying credentials.

### Will translate.js break my site's SEO?

The README says crawlers receive the page source unmodified, so indexing is not affected. That claim rests on the script running after the source is served, so verify what your own pages return to a crawler that does not execute JavaScript.

### Can translate.js translate content added by Vue or React after load?

Yes, if you call translate.listener.start(). The README describes it as monitoring page elements so that content changed by JavaScript is translated as well.

### Can translate.js be used without sending text to an external service?

The README lists private deployment of the translation API for projects with confidentiality requirements or no external network access, and it also describes an offline mode with a generated configuration file. Both require configuration beyond the four-line quick start.

## Sources

- [Issues](https://github.com/xnx3/translate/issues)
- [License: MIT](https://github.com/xnx3/translate/blob/master/LICENSE)
- [README](https://github.com/xnx3/translate/blob/master/README.md)
- [Releases](https://github.com/xnx3/translate/releases)
- [xnx3/translate on GitHub](https://github.com/xnx3/translate)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/xnx3-translate