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.