Registry / http-networking / google-translate-api

google-translate-api

JSON →
library2.3.0jsnpmunverified

The `google-translate-api` package provides a free and unlimited programmatic interface to Google Translate services. Unlike Google's official Cloud Translation APIs, this library functions as a wrapper around the public Google Translate website's frontend. It offers features such as automatic language detection, spelling correction, and language correction. The current stable version is 2.3.0, with recent updates focused on bug fixes, like handling `null` responses, and adding support for new languages. The package generally follows a patch and minor release cadence for ongoing maintenance. Its key differentiator is providing translation functionality without requiring API keys or incurring costs associated with Google Cloud Translate, making it suitable for hobby projects or those with budget constraints. However, developers should be aware that its reliance on reverse-engineering the Google Translate website means it can be susceptible to unannounced breaking changes if Google alters its front-end structure.

npm install google-translate-api
INSTALL
IMPORT
SIG · GOOGLE-TRANSLATE-A
G
google-translate-api
http-networkingjavascriptv2.3.0
Install
Import
Disk
Pass rate
0/ 6
Env Coverage0 / 6
glibc
1822
musl
1822
Install & Compatibility
Where this runs
tested against v? · npm install
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
musl
node 18226 runs
build_error
glibc
node 18226 runs
build_error
Code
Verified usage

Verified import paths — ran on the pinned version, not inferred.

translate
const translate = require('google-translate-api');
const { translate } = require('google-translate-api');
The primary export is a function, directly returned by `require()` in CommonJS.
translate (ESM)
import translate from 'google-translate-api';
import { translate } from 'google-translate-api';
For ESM environments, the CommonJS default export is consumed as a default import.
languages
const languages = require('google-translate-api/languages');
import { languages } from 'google-translate-api';
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.

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); });
Debug
Known issues
gotchaThis 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.
affects: >=2.0.0
breakingAs 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.
affects: >=2.2.0
gotchaPrior 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.
affects: <2.3.0
Errors
Common errors & fixes
TypeError: translate is not a function
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
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.
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.
Upgrade
Version history
2.3.0latest on npm
Audit
Dependencies

No dependency data recorded yet.

Agent activity
11 hits · last 30 days
node
10
OpenAI (training)
1
Resources
google-translate-api — npm install google-translate-api · libregistry