# @vitalets/google-translate-api > A free and unlimited API for Google Translate Latest version **9.2.1** (published 2025-01-21) · MIT license · 0 weekly downloads ## Install ```sh npm install @vitalets/google-translate-api pnpm add @vitalets/google-translate-api yarn add @vitalets/google-translate-api bun add @vitalets/google-translate-api ``` ## Health **Score 40/100 (D)** — status: maintenance-mode. Positive: has types; esm support; no vulnerabilities; high quality score. Warnings: low downloads. Negative: stale; low maintenance score. ## Facts | | | |---|---| | Version | 9.2.1 | | Published | 2025-01-21 | | First published | 2018-12-01 | | Weekly downloads | 0 | | License | MIT | | TypeScript types | bundled | | Module format | ESM + CommonJS | | Node | >=14 | | Dependencies | 3 | | Unpacked size | 30.8 KB | | Known vulnerabilities | 0 | | Install scripts | no | | GitHub stars | 1076 | | Maintainers | vitalets | | Keywords | translate, translator, google, api, free, language | ## Links - npm: https://www.npmjs.com/package/@vitalets/google-translate-api - Repository: https://github.com/vitalets/google-translate-api - Homepage: https://github.com/vitalets/google-translate-api#readme - Issues: https://github.com/vitalets/google-translate-api/issues - npm.io page: https://npm.io/package/@vitalets/google-translate-api ## Dependencies (3) - [node-fetch](https://npm.io/package/node-fetch.md) ^2.6.7 - [http-errors](https://npm.io/package/http-errors.md) ^2.0.0 - [@types/http-errors](https://npm.io/package/@types/http-errors.md) ^1.8.2 ## Alternatives - [ext-list](https://npm.io/package/ext-list.md) — 6.3M weekly downloads - [@lexical/selection](https://npm.io/package/@lexical/selection.md) — 3.8M weekly downloads - [@lexical/text](https://npm.io/package/@lexical/text.md) — 3.6M weekly downloads - [@lexical/clipboard](https://npm.io/package/@lexical/clipboard.md) — 3.0M weekly downloads - [@tiptap/extension-mention](https://npm.io/package/@tiptap/extension-mention.md) — 3.0M weekly downloads ## Recent versions - 9.2.1 (latest) — 2025-01-21 - 9.0.0-1 (next) — 2022-10-27 - 9.2.0 — 2023-05-12 - 9.1.0 — 2023-01-15 - 9.0.0 — 2022-11-01 - 9.0.0-0 — 2022-10-18 - 8.0.0 — 2022-02-28 - 7.0.0 — 2021-04-14 - 5.1.0 — 2021-03-03 - 5.0.0 — 2021-01-25 - 4.0.0 — 2020-08-23 - 3.0.0 — 2019-08-20 - 2.9.0 — 2019-07-30 - 2.8.0 — 2019-03-18 - 2.7.0 — 2019-02-13 - … 2 more at https://npm.io/package/@vitalets/google-translate-api/versions ## README # google-translate-api [![Actions Status](https://github.com/vitalets/google-translate-api/workflows/autotests/badge.svg)](https://github.com/vitalets/google-translate-api/actions) [![NPM version](https://img.shields.io/npm/v/@vitalets/google-translate-api.svg)](https://www.npmjs.com/package/@vitalets/google-translate-api) [![license](https://img.shields.io/npm/l/@vitalets/google-translate-api.svg)](https://www.npmjs.com/package/@vitalets/google-translate-api) A **free** and **unlimited** API for Google Translate for Node.js. **In version 9+ library was fully rewritten. For legacy documentation please see [legacy branch](https://github.com/vitalets/google-translate-api/tree/legacy).** > DISCLAIMER! To be 100% legal please use official [Google Translate API](https://cloud.google.com/translate). This project is mainly for pet projects and prototyping. ## Contents - [Features](#features) - [Installation](#installation) - [Usage](#usage) * [Node.js](#nodejs) * [React-native](#react-native) * [Web pages](#web-pages) * [Browser extensions](#browser-extensions) - [Limits](#limits) - [API](#api) + [Parameters](#parameters) + [Response](#response) - [Related projects](#related-projects) - [License](#license) ## Features * auto language detection * all [Google Translate languages](https://cloud.google.com/translate/docs/languages) supported * react-native supported * transliteration ## Installation ``` npm install @vitalets/google-translate-api ``` ## Usage ### Node.js ```ts import { translate } from '@vitalets/google-translate-api'; const { text } = await translate('Привет, мир! Как дела?', { to: 'en' }); console.log(text) // => 'Hello World! How are you?' ``` ### React-native Since react-native has [full support of fetch API](https://reactnative.dev/docs/network) translation works the same way as in Node.js. ### Web pages This library **does not work inside web pages** because `translate.google.com` does not provide [CORS](https://developer.mozilla.org/en-US/docs/Web/HTTP/CORS) headers allowing access from other domains. ### Browser extensions Although library does not work in regular web pages it can be used in browser extensions. Extensions background and popup pages are [not limited](https://developer.chrome.com/docs/extensions/mv3/xhr/) with same origin policy. To use translation API you should do the following: 1. Add host permissions to `manifest.json`: ```diff + "host_permissions": [ + "https://translate.google.com/" + ] ``` 2. Import `translate` as usual in background or popup script: ```js // background.js import { translate } from '@vitalets/google-translate-api'; const { text } = await translate('Привет мир'); console.log(text); ``` 3. Bundle code (for example with `webpack`): ```js // webpack.config.js module.exports = { mode: 'development', entry: './background.js', output: { filename: 'bundle.js', }, }; ``` ## Limits Google Translate has request limits. If too many requests are made from the same IP address, you will get a **TooManyRequestsError** (code 429). You can use **proxy** to bypass it: ```ts import { translate } from '@vitalets/google-translate-api'; import { HttpProxyAgent } from 'http-proxy-agent'; const agent = new HttpProxyAgent('http://103.152.112.162:80'); const { text } = await translate('Привет, мир!', { to: 'en', fetchOptions: { agent }, }); ``` See [examples/with-proxy.ts] for more details. > Available proxy list you can find [here](https://free-proxy-list.net/) (with `anonymous` in **Anonymity* and `yes` in *Google* columns). Common pattern for selecting proxy is following: ```ts try { const { text } = await translate('Привет, мир!', { to: 'en', fetchOptions: { agent }, }); } catch (e) { if (e.name === 'TooManyRequestsError') { // retry with another proxy agent } } ``` See [#107](https://github.com/vitalets/google-translate-api/issues/107) for discussion. ## API ```ts translate(text: string, options?: Options): Promise ``` #### Parameters * `text` *(string)* - The text to be translated * `options` *(object)* - `from` *(string)* - The language of `text`. Must be `auto` or one of the [supported languages](https://cloud.google.com/translate/docs/languages). Default: `auto` - `to` *(string)* - The language in which the text should be translated. Must be one of the [supported languages](https://cloud.google.com/translate/docs/languages). Default: `auto` - `host` *(string)* - Google translate host to be used in API calls. Default: `translate.google.com` - `fetchOptions` *(object)* - Additional [fetch options](https://developer.mozilla.org/en-US/docs/Web/API/fetch#parameters) passed into request. #### Response * `text` *(string)* – The translated text. * `raw` *(object)* - Raw responspe from the API. Contains sentences, detected original language and transliteration. [Example response](https://github.com/vitalets/google-translate-api/blob/master/response-sample.json). ## Related projects * [matheuss/google-translate-api](https://github.com/matheuss/google-translate-api) - original repo * [Translateer](https://github.com/Songkeys/Translateer) - uses Puppeteer to access Google Translate API * [hua1995116/google-translate-open-api](https://github.com/hua1995116/google-translate-open-api) * [google-translate-api-x](https://github.com/AidanWelch/google-translate-api) ## License MIT © [Matheus Fernandes](http://matheus.top), forked and maintained by [Vitaliy Potapov](https://github.com/vitalets). Buy Me A Coffee --- _Source: https://npm.io/package/@vitalets/google-translate-api · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._