google-translate-api

google-translate-api-x is a maintained fork of the original vitalets/google-translate-api that talks directly to the same servers translate.google.com uses, giving Node.js, browser-extension, and React Native code free and unlimited machine translation without an API key or Google Cloud billing account. It supports both of Google’s undocumented endpoints — the more accurate but easily rate-limited single-translate endpoint, and the batch-translate endpoint used as the default and as an automatic fallback — so callers can trade off accuracy against the risk of a 429.

Beyond plain text translation, the package exposes a Translator class for reusing options across calls, array/object batch inputs that fold many strings into one request, spelling/language auto-correction surfaced through autoCorrect and didYouMean fields, and a speak() method that returns Base64-encoded MP3 text-to-speech audio. A pluggable requestFunction (defaulting to fetch) lets consumers swap in proxy agents or custom HTTP clients for environments where direct requests get rate-limited or blocked by CORS.

What You Get

• A translate() function that auto-detects the source language and returns translated text, pronunciation, and auto-correction metadata
• Automatic fallback from the accurate-but-rate-limited single-translate endpoint to the more resilient batch-translate endpoint
• Batch translation of arrays or keyed objects of strings in a single network request, each with optional per-item language overrides
• A speak() method returning Base64 MP3 text-to-speech audio for any supported target language
• A Translator class for persisting default options (from/to/tld/etc.) across repeated translate calls
• Full TypeScript type definitions (index.d.ts) shipped with the package

Common Use Cases

• Adding free machine translation to a hobby project or browser extension without Google Cloud billing
• Bulk-translating UI strings or product descriptions in one batched request instead of one call per string
• Producing spoken pronunciation audio for translated text via the built-in TTS endpoint
• Running translation calls from React Native or extension background scripts where CORS blocks direct Google Cloud API calls

Under The Hood

Architecture The package is a thin, single-purpose wrapper: index.cjs re-exports translate (from lib/translation/translate.cjs), the Translator class, singleTranslate, batchTranslate, speak, and the languages table. translate.cjs is a small dispatcher that merges caller options over DEFAULT_OPTIONS (frozen in lib/defaults.cjs) and routes string input to singleTranslate unless forceBatch is set, falling back to batchTranslate on failure when fallbackBatch is true; any non-string input always goes through batchTranslate. Both translation modules build a request against a different undocumented Google Translate URL (/translate_a/single for single, /_/TranslateWebserverUi/data/batchexecute for batch), call the pluggable requestFunction (default fetch), and parse Google’s idiosyncratic nested-array JSON response into a shared TranslationResult class that normalizes text, pronunciation, and from.language/from.text correction metadata. There is no persistent state or database — every call is stateless aside from the frozen defaults object, so the only thing that would break on a change to the core abstraction is the response-parsing logic tied to Google’s undocumented wire format.

Tech Stack The library is plain CommonJS JavaScript (index.cjs, lib/**/*.cjs) with zero runtime dependencies, relying on the global fetch (Node 21+ per engines) and URLSearchParams. Type definitions are hand-written in index.d.ts and validated with tsd. Dev tooling is ESLint 10 (flat config via eslint.config.mjs) with eslint-plugin-mocha and eslint-plugin-n, Mocha for the test runner, and np for release publishing. There is no bundler or transpiler step — the package ships its .cjs sources directly as both main and module.

Code Quality Tests live under test/ as Mocha specs (.test.mjs/.test.cjs) covering translate, Translator, singleTranslate, batchTranslate, languages, and speak, plus a tsd-driven type test (index.test-d.ts). Tests make live network calls against the real Google Translate endpoints (with this.retries(10) to absorb rate-limit flakiness) rather than mocking responses, which makes CI runs somewhat dependent on Google’s servers being reachable and not currently rate-limiting the CI IP. Error handling is explicit: unsupported language codes and partial batch failures throw Error objects carrying a cause object with the original options/URL/response for debuggability. Naming is consistent camelCase, and a GitHub Actions workflow (autotests) runs npm test on push, PR, and a daily cron against Node 18.

What Makes It Unique Unlike most Google Translate wrapper packages, which pick either the single or the batch endpoint, this fork deliberately supports both and adds automatic fallback between them — directly motivated by the original package’s issues with endpoint-specific rate limiting. It also adds a TTS speak() method, forceable ISO codes for languages not yet in its bundled table, array/object batch inputs with per-item option overrides, and a pluggable request function so it can run in non-Node contexts like browser extensions and React Native where CORS or fetch differences would otherwise block direct calls.