1.1.6 • Published 10 months ago

@kabeep/node-translate v1.1.6

Weekly downloads
-
License
MIT
Repository
github
Last release
10 months ago

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


NodeJS License NPM Codecov Codacy CircleCI

English | 简体中文

Alt

📖 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);
ParameterTypeOptionalDefaultDescription
textstringNo-Source text, phrase or word.
optionsTranslateOptions--The options for translating.
options.fromLanguageCode, auto or stringYes'auto'The language name/ISO 639-1 code to translate from. If none is given, it will auto-detect the source language.
options.toLanguageCode, auto or stringYes'auto'The language name/ISO 639-1 code to translate to. If none is given, it will translate to native environment language.
options.rawbooleanYesfalseIf true, it will return the raw output that was received from Google Translation Api.
options.timeoutnumberYes30_000Timeout duration for the translation request in milliseconds.
options.retrynumberYes0Retry attempts for the translation request in case of failure.

Returns: Promise<TranslationOption>

Response Object:

KeyTypeDescription
textstringTranslation summary, long text will be truncated, please use to.text.value for complete results.
fromRecord-
from.languageRecord-
from.language.didYouMeanbooleanIndicates whether there is a language suggestion.
from.language.isostringThe ISO code of the detected language.
from.textRecord-
from.text.autoCorrectedbooleanIndicates whether there was an autocorrection.
from.text.valuestringSource text.
from.text.phoneticsstringPhonetic transcription of the source text.
from.text.didYouMeanbooleanIndicates whether a suggestion for the source text.
from.synonymsstring[]Synonyms of the source word.
from.sentencesstring[]Example sentence of the source word.
toRecord-
to.textRecord-
to.text.phoneticsstringPhonetic transcription of the translated text.
to.text.valuestringTranslated text.
to.polysemyArray<{ label: string; children: string[] }>Polysemy information for the translated text.
rawstringThe 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);
ParameterTypeOptionalDefaultDescription
codestringNo-Iso-639-1 language code or google translation language code.

Returns: string


Methods: getAllNames()

iso6391X.getAllNames();

Returns: string[]


Methods: getNativeName(code)

iso6391X.getNativeName(code);
ParameterTypeOptionalDefaultDescription
codestringNo-Iso-639-1 language code or google translation language code.

Returns: string


Methods: getAllNativeNames()

iso6391X.getAllNativeNames();

Returns: string[]


Methods: getCode(name)

iso6391X.getCode(name);
ParameterTypeOptionalDefaultDescription
namestringNo-Iso-639-1 language name or google translation language name.

Returns: LanguageCode


Methods: getAllCodes()

iso6391X.getAllCodes();

Returns: LanguageCode[]


Methods: getLanguages(codes)

iso6391X.getLanguages(codes);
ParameterTypeOptionalDefaultDescription
codesstring[]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

🤝 Contribution

Contributions via Pull Requests or Issues are welcome.

📄 License

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