Google Translate API

A Node.JS library to consume Google Translate for free.

Feature Highlights

• Automatically detect source language
• Automatic spelling corrections
• Automatic language correction
• Fast and reliable

Table of Contents

• Installation
• Usage
• Languages
• Errors
• Examples
• Development
• Credits, etc

Installation

Requires Node.js 22.19.0 or later.

# Stable version, from npm repository
npm install --save @iamtraction/google-translate

# Latest version, from GitHub repository
npm install --save iamtraction/google-translate

Usage

const translate = require('@iamtraction/google-translate');

Method: translate(text, options)

translate(text, options).then(console.log).catch(console.error);

Parameter	Type	Optional	Default	Description
text	String	No	-	The text you want to translate.
options	Object	-	-	The options for translating.
options.from	String	Yes	'auto'	The language name or code to translate from. If none is given, it will auto detect the source language.
options.to	String	Yes	'en'	The language name or code to translate to. If none is given, it will translate to English.
options.raw	Boolean	Yes	false	If true, it will return the raw output that was received from Google Translate.
options.dispatcher	Dispatcher	Yes	-	The undici dispatcher to make the request with.

Behind a proxy, set HTTP_PROXY, HTTPS_PROXY and NO_PROXY. Pass options.dispatcher to take over entirely. Without either, undici's global dispatcher is used.

Returns: Promise<Object>

Response Object:

Key	Type	Description
text	String	The translated text.
from	Object	-
from.language	Object	-
from.language.didYouMean	Boolean	Whether or not the API suggest a correction in the source language.
from.language.iso	String	The code of the language that the API has recognized in the text.
from.text	Object	-
from.text.autoCorrected	Boolean	Whether or not the API has auto corrected the original text.
from.text.value	String	The auto corrected text or the text with suggested corrections, or "" unless from.text.autoCorrected or from.text.didYouMean is true.
from.text.didYouMean	Boolean	Wherether or not the API has suggested corrections to the text
raw	Array	The raw response from Google Translate servers, or "" unless options.raw is true in the request options.

Languages

translate.languages is the table of supported languages, keyed by code, with two helpers attached.

translate.languages['pa-Arab'];              // OUTPUT: Punjabi (Shahmukhi)
translate.languages.getCode('Spanish');   // OUTPUT: es
translate.languages.isSupported('klingon');  // OUTPUT: false

getCode accepts a code or a display name, case insensitively, and returns the code in its canonical casing or null if it isn't supported. The helpers are non-enumerable, so iterating the table yields only languages.

Errors

Rejections carry a name to tell them apart and a code with HTTP semantics.

name	code	Thrown when
UnsupportedLanguageError	400	options.from or options.to is not a supported language. No request is made.
TranslateResponseError	The response status	Google Translate answered with a status other than 200.
TranslateResponseError	502	Google Translate answered 200 with a body that could not be parsed. The original parse error is on err.cause.

Match on name rather than code, as an upstream rejection also reports 400.

translate('Tu es incroyable!', { to: 'klingon' }).catch(err => {
  if (err.name === 'UnsupportedLanguageError') console.error(err.message);
});

Examples

From automatic language detection to English:

translate('Tu es incroyable!', { to: 'en' }).then(res => {
  console.log(res.text); // OUTPUT: You are amazing!
}).catch(err => {
  console.error(err);
});

From English to French, with a typo:

translate('Thnk you', { from: 'en', to: 'fr' }).then(res => {
  console.log(res.text); // OUTPUT: Merci
  console.log(res.from.text.autoCorrected); // OUTPUT: true
  console.log(res.from.text.value); // OUTPUT: [Thank] you
  console.log(res.from.text.didYouMean); // OUTPUT: false
}).catch(err => {
  console.error(err);
});

Sometimes Google Translate won't auto correct:

translate('I spea Dutch!', { from: 'en', to: 'nl' }).then(res => {
  console.log(res.text); // OUTPUT: Ik spreek Nederlands!
  console.log(res.from.text.autoCorrected); // OUTPUT: false
  console.log(res.from.text.value); // OUTPUT: I [speak] Dutch!
  console.log(res.from.text.didYouMean); // OUTPUT: true
}).catch(err => {
  console.error(err);
});

Development

npm run lint          # ESLint
npm test              # the test suite
npm run test:coverage # the test suite with a coverage report for src/

Lint is separate from tests and is not run by npm test — CI runs it as its own step, and a habit of running npm test alone will skip it.

Most of the suite runs offline: languages, request, parse, and errors mock the transport through the public dispatcher option, so they assert what this library does — the request it builds, how it parses the response, how it validates and reports errors — without a network call. Only test/smoke.test.js reaches the real translate.google.com, so a red run there may be Google rate limiting rather than a regression. It checks only that a live response still parses into the expected shape; whether a translation is correct is Google's concern, not this library's, so no test asserts translated content.

To run just the offline suites: node --test test/languages.test.js test/request.test.js test/parse.test.js test/errors.test.js.

Extras

If you liked this project, please give it a ⭐ in GitHub.

Credits to matheuss for writing the original version of this library. I rewrote this, with improvements and without using many external libraries, as his library was not actively developed and had vulnerabilities.