{"id":16367,"library":"google-translate-api","title":"Google Translate API Wrapper (Unofficial)","description":"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.","status":"active","version":"2.3.0","language":"javascript","source_language":"en","source_url":"https://github.com/matheuss/google-translate-api","tags":["javascript","translate","translator","google","api","free","language"],"install":[{"cmd":"npm install google-translate-api","lang":"bash","label":"npm"},{"cmd":"yarn add google-translate-api","lang":"bash","label":"yarn"},{"cmd":"pnpm add google-translate-api","lang":"bash","label":"pnpm"}],"dependencies":[],"imports":[{"note":"The primary export is a function, directly returned by `require()` in CommonJS.","wrong":"const { translate } = require('google-translate-api');","symbol":"translate","correct":"const translate = require('google-translate-api');"},{"note":"For ESM environments, the CommonJS default export is consumed as a default import.","wrong":"import { translate } from 'google-translate-api';","symbol":"translate (ESM)","correct":"import translate from 'google-translate-api';"},{"note":"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.","wrong":"import { languages } from 'google-translate-api';","symbol":"languages","correct":"const languages = require('google-translate-api/languages');"}],"quickstart":{"code":"const translate = require('google-translate-api');\n\nconsole.log('Starting translation examples...');\n\n// Example 1: Auto-detect language and translate to English\ntranslate('Ik spreek Engels', { to: 'en' })\n    .then(res => {\n        console.log('--- Example 1: Auto-detect to English ---');\n        console.log('Original Text: \"Ik spreek Engels\"');\n        console.log('Translated Text:', res.text);\n        console.log('Detected Source Language (ISO):', res.from.language.iso);\n        console.log('-------------------------------------------\\n');\n    })\n    .catch(err => {\n        console.error('Error in Example 1:', err);\n    });\n\n// Example 2: Translate from English to Dutch with a typo, demonstrating auto-correction\ntranslate('I spea Dutch!', { from: 'en', to: 'nl' })\n    .then(res => {\n        console.log('--- Example 2: English to Dutch with Typo ---');\n        console.log('Original Text: \"I spea Dutch!\"');\n        console.log('Translated Text:', res.text);\n        console.log('Source Text Auto-Corrected:', res.from.text.autoCorrected);\n        if (res.from.text.autoCorrected || res.from.text.didYouMean) {\n            console.log('Corrected/Suggested Source Value:', res.from.text.value);\n        }\n        console.log('-------------------------------------------\\n');\n    })\n    .catch(err => {\n        console.error('Error in Example 2:', err);\n    });\n\n// Example 3: Demonstrating raw output option\ntranslate('Hello World', { to: 'es', raw: true })\n    .then(res => {\n        console.log('--- Example 3: Raw Output ---');\n        console.log('Translated Text (from raw):', res.text);\n        console.log('Raw API Response (truncated):', res.raw.substring(0, 100), '...');\n        console.log('-------------------------------------------\\n');\n    })\n    .catch(err => {\n        console.error('Error in Example 3:', err);\n    });","lang":"javascript","description":"Demonstrates basic text translation with automatic language detection, handling of spelling corrections, and retrieving the raw API response for debugging or advanced parsing."},"warnings":[{"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.","message":"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.","severity":"gotcha","affected_versions":">=2.0.0"},{"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.","message":"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.","severity":"breaking","affected_versions":">=2.2.0"},{"fix":"Upgrade to `google-translate-api@^2.3.0` or newer to resolve issues with `null` values in Google's responses.","message":"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.","severity":"gotcha","affected_versions":"<2.3.0"}],"env_vars":null,"last_verified":"2026-04-22T00:00:00.000Z","next_check":"2026-07-21T00:00:00.000Z","problems":[{"fix":"For CommonJS, use `const translate = require('google-translate-api');`. For ESM, use `import translate from 'google-translate-api';`.","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.","error":"TypeError: translate is not a function"},{"fix":"Update the package to `google-translate-api@^2.3.0` or newer to get the fix for handling `null` responses gracefully.","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.","error":"Error: BAD_NETWORK"},{"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.","cause":"Since `v2.2.0`, providing an invalid or unsupported language code in the `from` or `to` options will explicitly reject the translation promise.","error":"Unhandled Promise Rejection: The language 'xxx' is not supported."}],"ecosystem":"npm"}