Google Translate API Wrapper (Unofficial)

Common errors

• TypeError: translate is not a function

  cause Attempting to use named import syntax (e.g., `import { translate } from 'google-translate-api';`) in an ESM context or incorrectly destructuring `require()` for a default/single function export.
  fix For CommonJS, use `const translate = require('google-translate-api');`. For ESM, use `import translate from 'google-translate-api';`.

• Error: BAD_NETWORK

  cause This error, often accompanied by a message about unexpected `null` values, indicated a parsing failure due to specific response structures from Google Translate. This was a known bug in versions prior to 2.3.0.
  fix Update the package to `google-translate-api@^2.3.0` or newer to get the fix for handling `null` responses gracefully.

• Unhandled Promise Rejection: The language 'xxx' is not supported.

  cause Since `v2.2.0`, providing an invalid or unsupported language code in the `from` or `to` options will explicitly reject the translation promise.
  fix Ensure that the language codes passed to `from` and `to` options are valid. You can use the `google-translate-api/languages` module to check for supported languages programmatically.

Warnings

• gotcha This package operates by reverse-engineering Google Translate's public web interface, not the official Google Cloud Translation API. This means Google can make unannounced changes to their frontend at any time, which may cause this library to break or behave unexpectedly without warning until an update is released. It does not offer the same reliability, support, or features (e.g., specific models, robust rate limiting, legal compliance) as the official API.
  Fix: Be prepared for potential breakage and consider actively monitoring the library's GitHub repository for updates or issues. For production-critical applications, consider using the official Google Cloud Translation API.
• breaking As of `v2.2.0`, passing unsupported or invalid language codes to the `from` or `to` options will now cause the translation Promise to be explicitly rejected. Previous versions might have silently defaulted to a different language or returned an undefined result, which could lead to unexpected behavior if not handled.
  Fix: Implement robust error handling for `translate` calls and use the `google-translate-api/languages` module (if available) or refer to the `languages.js` file to validate language codes before making a translation request.
• gotcha Prior to `v2.3.0`, the library had a known issue where it could throw `BAD_NETWORK` errors (or similar) if Google's API response contained `null` values. This could lead to application crashes or failed translations.
  Fix: Upgrade to `google-translate-api@^2.3.0` or newer to resolve issues with `null` values in Google's responses.

Install

• npm install google-translate-api npm
• yarn add google-translate-api yarn
• pnpm add google-translate-api pnpm

Imports

• translate
  wrong:

  const { translate } = require('google-translate-api');

  correct:

  const translate = require('google-translate-api');

  The primary export is a function, directly returned by `require()` in CommonJS.
• translate (ESM)
  wrong:

  import { translate } from 'google-translate-api';

  correct:

  import translate from 'google-translate-api';

  For ESM environments, the CommonJS default export is consumed as a default import.
• languages
  wrong:

  import { languages } from 'google-translate-api';

  correct:

  const languages = require('google-translate-api/languages');

  The `languages` module, containing utilities for language handling, is accessed via a subpath import in CommonJS. Direct named ESM imports from the main package are not supported in 2.x.

Quickstart

Demonstrates basic text translation with automatic language detection, handling of spelling corrections, and retrieving the raw API response for debugging or advanced parsing.

const translate = require('google-translate-api');

console.log('Starting translation examples...');

// Example 1: Auto-detect language and translate to English
translate('Ik spreek Engels', { to: 'en' })
    .then(res => {
        console.log('--- Example 1: Auto-detect to English ---');
        console.log('Original Text: "Ik spreek Engels"');
        console.log('Translated Text:', res.text);
        console.log('Detected Source Language (ISO):', res.from.language.iso);
        console.log('-------------------------------------------\n');
    })
    .catch(err => {
        console.error('Error in Example 1:', err);
    });

// Example 2: Translate from English to Dutch with a typo, demonstrating auto-correction
translate('I spea Dutch!', { from: 'en', to: 'nl' })
    .then(res => {
        console.log('--- Example 2: English to Dutch with Typo ---');
        console.log('Original Text: "I spea Dutch!"');
        console.log('Translated Text:', res.text);
        console.log('Source Text Auto-Corrected:', res.from.text.autoCorrected);
        if (res.from.text.autoCorrected || res.from.text.didYouMean) {
            console.log('Corrected/Suggested Source Value:', res.from.text.value);
        }
        console.log('-------------------------------------------\n');
    })
    .catch(err => {
        console.error('Error in Example 2:', err);
    });

// Example 3: Demonstrating raw output option
translate('Hello World', { to: 'es', raw: true })
    .then(res => {
        console.log('--- Example 3: Raw Output ---');
        console.log('Translated Text (from raw):', res.text);
        console.log('Raw API Response (truncated):', res.raw.substring(0, 100), '...');
        console.log('-------------------------------------------\n');
    })
    .catch(err => {
        console.error('Error in Example 3:', err);
    });