Google Translate Unofficial API

1.0.4 · active · verified Tue Apr 21

The `translate-google-api` library provides a free and unofficial interface to Google Translate services, supporting both single and multi-segment text translation. As of version 1.0.4, it offers a programmatic way to interact with Google Translate without requiring official, paid Google Cloud Translation API tokens. A key differentiator is its ability to handle multi-segment text efficiently within a single request, addressing limitations found in some alternative unofficial libraries which might require multiple requests for segmented content. It aims to provide a reliable translation service by leveraging the same servers used by `translate.google.com` and includes comprehensive proxy support for complex network configurations. This package is compatible with ReactJS, React Native, and Node.js environments. While no explicit release cadence is stated, updates appear to be made as needed, primarily focusing on stability and feature enhancements. Being an unofficial client, its long-term stability is dependent on Google's public translation endpoint.

Common errors

```
Error: Request failed with status code 429
```
cause Google has temporarily blocked or rate-limited your IP address due to excessive requests.

fix Reduce the frequency of your translation requests, implement backoff/retry mechanisms, or use proxy servers to rotate IP addresses. Wait for some time before retrying.
```
Error: connect ECONNREFUSED 127.0.0.1:9000
```
cause The application could not establish a connection to the specified proxy server. This typically means the proxy is not running or is configured incorrectly.

fix Verify that your proxy server (e.g., at `127.0.0.1:9000`) is running and accessible. Check proxy configuration in `translate` options, including host, port, and authentication details.
```
TypeError: translate is not a function
```
cause This error usually indicates an incorrect import statement, especially when mixing CommonJS `require` with ES Modules `import` or attempting a named import for a default export.

fix For ES Modules, use `import translate from 'translate-google-api';`. For CommonJS, use `const translate = require('translate-google-api');`. Do not use `import { translate } from 'translate-google-api';`.

Warnings

breaking As an unofficial API, `translate-google-api` is not guaranteed by Google and can break without notice if Google changes its underlying translation service endpoints or token mechanisms.
Fix: Monitor the GitHub repository for updates and potential fixes. Consider official Google Cloud Translation API for production systems requiring guaranteed stability.
gotcha Heavy usage may lead to Google rate-limiting your requests, resulting in HTTP 429 Too Many Requests errors. This is a common issue with unofficial APIs.
Fix: Implement exponential backoff and retry logic in your application. Consider distributing requests over time or using multiple IP addresses via a proxy rotation. For high-volume needs, explore the official Google Cloud Translation API.
gotcha The `tld` option (`'com'` or `'cn'`) affects which Google Translate server endpoint is used. Misconfiguring this for your region can lead to slower responses or network errors.
Fix: Ensure `tld` is set appropriately for your geographic location and target audience. Use `'cn'` if your application primarily serves users in China or requires routing through Chinese servers, otherwise stick with the default `'com'`.

Install

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

Imports

translate
wrong:
```
const translate = require('translate-google-api');
```
correct:
```
import translate from 'translate-google-api';
```
The primary translation function is a default export. Prefer ESM imports for modern Node.js and browser environments.
translate (CommonJS)
wrong:
```
import { translate } from 'translate-google-api';
```
correct:
```
const translate = require('translate-google-api');
```
While CommonJS `require` works in Node.js, it's generally discouraged in new projects favoring ESM. Do not use named import syntax for this default export.
TranslateOptions
wrong:
```
import { TranslateOptions } from 'translate-google-api';
```
correct:
```
import type { TranslateOptions } from 'translate-google-api';
```
To import the TypeScript interface for translation options, use a type-only import to avoid bundling issues and ensure proper type checking.

Quickstart

This quickstart demonstrates how to use `translate-google-api` to translate multiple text segments simultaneously, specifying source and target languages, and illustrates error handling.

import translate from 'translate-google-api';

async function performTranslation() {
  const textToTranslate = [
    process.env.TEXT_SEGMENT_1 ?? 'Hello world!',
    process.env.TEXT_SEGMENT_2 ?? 'How are you today?',
    process.env.TEXT_SEGMENT_3 ?? 'This is a test of multi-segment translation.'
  ];
  const targetLanguage = process.env.TO_LANG ?? 'es'; // Translate to Spanish by default
  const fromLanguage = process.env.FROM_LANG ?? 'auto'; // Auto-detect source language

  try {
    const result = await translate(textToTranslate, {
      from: fromLanguage,
      to: targetLanguage,
      tld: process.env.GOOGLE_TLD ?? 'com' // Use 'cn' for China, 'com' for others
    });
    console.log(`Translated from '${fromLanguage}' to '${targetLanguage}':`);
    result.forEach((segment, index) => {
      console.log(`Segment ${index + 1}: ${textToTranslate[index]} -> ${segment}`);
    });
  } catch (error) {
    console.error('Translation failed:', error.message);
  }
}

performTranslation();

view raw JSON →