A powerful, secure and feature-rich api via Google Translation.

---

English | 简体中文

📖 Introduction

Thank you to matheuss and iamtraction for writing the original version of this library. Due to the original authors no longer actively maintaining it, I rewrote the library using TypeScript and ISO-639-1. This rewrite has made the program more secure, provided richer translation results, and resolved program anomalies.

What's New?

• Adaptive native language translation.
• Synonyms, polysemous explanations, and example sentences.
• Timeout and retry parameters in complex networks.
• Support for querying language, language code, native language, and adaptive language lists.
• Support for ISO-639-1, minority languages, special languages, and the latest changes on Wikipedia.
• Secure API types and comprehensive coverage.
• Controllable error states.

⚙️ Installation

npm install @kabeep/node-translate --save

yarn add @kabeep/node-translate

pnpm add @kabeep/node-translate

🚀 Usage

import translate from '@kabeep/node-translate';

Methods: translate(text, options)

translate(text, options)
    .then(console.log)
    .catch(console.error);

Parameter	Type	Optional	Default	Description
text	string	No	-	Source text, phrase or word.
options	TranslateOptions	-	-	The options for translating.
options.from	LanguageCode, auto or string	Yes	'auto'	The language name/ISO 639-1 code to translate from. If none is given, it will auto-detect the source language.
options.to	LanguageCode, auto or string	Yes	'auto'	The language name/ISO 639-1 code to translate to. If none is given, it will translate to native environment language.
options.raw	boolean	Yes	false	If true, it will return the raw output that was received from Google Translation Api.
options.timeout	number	Yes	30_000	Timeout duration for the translation request in milliseconds.
options.retry	number	Yes	0	Retry attempts for the translation request in case of failure.

Returns: Promise<TranslationOption>

Response Object:

Key	Type	Description
text	string	Translation summary, long text will be truncated, please use to.text.value for complete results.
from	Record	-
from.language	Record	-
from.language.didYouMean	boolean	Indicates whether there is a language suggestion.
from.language.iso	string	The ISO code of the detected language.
from.text	Record	-
from.text.autoCorrected	boolean	Indicates whether there was an autocorrection.
from.text.value	string	Source text.
from.text.phonetics	string	Phonetic transcription of the source text.
from.text.didYouMean	boolean	Indicates whether a suggestion for the source text.
from.synonyms	string[]	Synonyms of the source word.
from.sentences	string[]	Example sentence of the source word.
to	Record	-
to.text	Record	-
to.text.phonetics	string	Phonetic transcription of the translated text.
to.text.value	string	Translated text.
to.polysemy	Array<{ label: string; children: string[] }>	Polysemy information for the translated text.
raw	string	The raw response body from the translation request. Only returned if options.raw is true in the request options.

---

import { iso6391X } from '@kabeep/node-translate';

Methods: getName(code)

iso6391X.getName(code);

Parameter	Type	Optional	Default	Description
code	string	No	-	Iso-639-1 language code or google translation language code.

Returns: string

---

Methods: getAllNames()

iso6391X.getAllNames();

Returns: string[]

---

Methods: getNativeName(code)

iso6391X.getNativeName(code);

Parameter	Type	Optional	Default	Description
code	string	No	-	Iso-639-1 language code or google translation language code.

Returns: string

---

Methods: getAllNativeNames()

iso6391X.getAllNativeNames();

Returns: string[]

---

Methods: getCode(name)

iso6391X.getCode(name);

Parameter	Type	Optional	Default	Description
name	string	No	-	Iso-639-1 language name or google translation language name.

Returns: LanguageCode

---

Methods: getAllCodes()

iso6391X.getAllCodes();

Returns: LanguageCode[]

---

Methods: getLanguages(codes)

iso6391X.getLanguages(codes);

Parameter	Type	Optional	Default	Description
codes	string[]	No	-	Iso-639-1 language codes or google translation language codes.

Returns: LanguageOption[]

---

Methods: getAllDetections()

iso6391X.getAllDetections();

Returns: LanguageCode[]

🪄 Examples

Usage of language codes

View Case

import translate from '@kabeep/node-translate';

// Simple example
translate('例子', { to: 'en' }).then(res => {
    // => example
    console.log(res.to.text.value);
});

Using language name and capitalized correction

View Case

import translate from '@kabeep/node-translate';

// Language name and capitalized correction
translate('例子', { to: 'ENGlish' }).then(res => {
    // => example
    console.log(res.text);
});

Adaptive translation

View Case

import translate from '@kabeep/node-translate';

// Use `auto` or leave the `from` parameter empty to detect language by adativeness
// Use `auto` or leave the `to` parameter empty to detect language by os (`en` for example)
translate('例子').then(res => {
    // => example
    console.log(res.text);
});

Phonetic transcription of the source text and translation

View Case

import translate from '@kabeep/node-translate';

// Output phonetic transcription of the source text and the translated text
translate('例子', { to: 'ja' }).then(res => {
    // => Lìzi
    console.log(res.from.text.phonetics);
    // => Rei
    console.log(res.to.text.phonetics);
});

Synonymous and similar words in the source text

View Case

import translate from '@kabeep/node-translate';

// Output synonyms of the source word
translate('例子', { to: 'en' }).then(res => {
    // =>
    // [
    //     '例',
    //     '例子',
    //     '范例',
    //     '榜样',
    //     '典范',
    //     '例证',
    // ]
    console.log(res.from.synonyms);
});

Source text example sentences

View Case

import translate from '@kabeep/node-translate';

// Output example sentence of the source word
translate('example', { to: 'zh' }).then(res => {
    // => [
    //     "it is vitally important that parents should set an [example]",
    //     "she followed her brother's [example] and deserted her family",
    //     "it's a good [example] of how European action can produce results",
    // ]
    console.log(res.from.sentences);
});

Synonymous translation

View Case

import translate from '@kabeep/node-translate';

// Output polysemy information for the translated text
translate('例子', { to: 'en' }).then(res => {
    // => [{
    //     label: 'noun',
    //     children: [
    //         'example',
    //         'case',
    //         'instance',
    //     ],
    // }]
    console.log(res.to.polysemy);
});

Source text suggestions

View Case

import translate from '@kabeep/node-translate';

// Automatically detect and use the correct source text of suggested
translate('Thunk you', { from: 'en', to: 'zh' }).then(res => {
    // => 谢谢你
    console.log(res.to.text.value);
    // => true
    console.log(res.from.text.didYouMean);
});

Automatic correction of source text

View Case

import translate from '@kabeep/node-translate';

// Automatically correct spelling errors in the source text
translate('Thnak you', { from: 'en', to: 'zh' }).then(res => {
    // => 谢谢
    console.log(res.to.text.value);
    // => true
    console.log(res.from.text.autoCorrected);
});

Automatic correction of source language codes

View Case

import translate from '@kabeep/node-translate';

// Automatically detect and use correct source language codes of suggested
translate('example', { from: 'zh', to: 'en' }).then(res => {
    // => en
    console.log(res.from.language.iso);
    // => true
    console.log(res.from.language.didYouMean);
});

// Automatically detect and use the correct source text of suggested
translate('Thunk you', { from: 'en', to: 'zh' }).then(res => {
    // => 谢谢你
    console.log(res.to.text.value);
    // => true
    console.log(res.from.text.didYouMean);
});

Network exception retry

View Case

import translate from '@kabeep/node-translate';

// Retry attempts for the translation request in case of failure (with a maximum of three requests)
translate('例子', { to: 'en', retry: 2, timeout: 100 }).catch((err) => {
    // => ETIMEDOUT    - The timeout limits was reached
    // => ECONNRESET   - The connection was forcibly closed
    // => EADDRINUSE   - Could not bind to any free port
    // => ECONNREFUSED - The connection was refused by the server
    // => EPIPE        - The remote side of the stream being written has been closed
    // => ENOTFOUND    - Could not resolve the hostname to an IP address
    // => ENETUNREACH  - No internet connection
    // => EAI_AGAIN    - DNS lookup timed out
    // => EPARSE       - Unexpected API response data
    // => EVALIDATION  - Illegal language code
    console.log(err.message);
});

ISO-639-1-X

View Case

import { iso6391X, LanguageCode, LanguageOption } from '@kabeep/node-translate';

// => en
console.log(iso6391X.getCode('english'));

// => ['aa', 'ab', ... 199 more items]
console.log(iso6391X.getAllCodes());

// => English
console.log(iso6391X.getName('en'));

// => ['Afar', 'Abkhaz', ... 199 more items]
console.log(iso6391X.getAllNames());

// => 中文
console.log(iso6391X.getNativeName('zh'));

// => ['Afaraf', 'аҧсуа бызшәа', ... 199 more items]
console.log(iso6391X.getAllNativeNames());

// => [
//   { code: 'en', name: 'English', nativeName: 'English' },
//   { code: 'zh', name: 'Chinese', nativeName: '中文' },
//   ... 6 more items
// ]
console.log(iso6391X.getAllDetections());

// => [
//   { code: 'en', name: 'English', nativeName: 'English' },
//   { code: 'zh', name: 'Chinese', nativeName: '中文' },
// ]
console.log(iso6391X.getLanguages(['en', 'zh']));

// => true
console.log(iso6391X.validate('en'));
// => false
console.log(iso6391X.validate('english'));

🔗 Related

• google-translate-api - A free and unlimited API for Google Translate 💵🚫
• google-translate - 🈯 A Node.JS library to consume Google Translate API for free.

🤝 Contribution

Contributions via Pull Requests or Issues are welcome.

📄 License

This project is licensed under the MIT License. See the LICENSE file for details.