Merge pull request #35 from plainheart/v4-MET

feat: new MET mode for Microsoft Translator

Author: plainheart

.github/workflows/autotest.yml

@@ -12,22 +12,12 @@ jobs:
     if: ${{ github.repository_owner == 'plainheart' }}
     runs-on: ubuntu-latest
 
-    strategy:
-      matrix:
-        node-version: ['20.x']
-
     steps:
       - uses: actions/checkout@v4
 
-      - name: Use Node.js ${{ matrix.node-version }}
-        uses: actions/setup-node@v4
-        with:
-          node-version: ${{ matrix.node-version }}
-          registry-url: https://registry.npmjs.org/
-
       - name: Cache node modules
         id: cache
-        uses: actions/cache@v3
+        uses: actions/cache@v4
         env:
           cache-name: cache-node-modules
         with:

README.md

@@ -1,21 +1,27 @@
-<!-- AUTO-GENERATED. SEE scripts/README.tpl.md FOR ORIGINAL TEMPLATE -->
-
 # bing-translate-api
 [![NPM version](https://img.shields.io/npm/v/bing-translate-api.svg?style=flat)](https://www.npmjs.org/package/bing-translate-api)
 [![Auto Test](https://github.com/plainheart/bing-translate-api/actions/workflows/autotest.yml/badge.svg)](https://github.com/plainheart/bing-translate-api/actions/workflows/autotest.yml)
 [![NPM Downloads](https://img.shields.io/npm/dm/bing-translate-api.svg)](https://npmcharts.com/compare/bing-translate-api?minimal=true)
 [![License](https://img.shields.io/npm/l/bing-translate-api.svg)](https://github.com/plainheart/bing-translate-api/blob/master/LICENSE)
 
-A **simple** and **free** API for [Bing Translator](https://bing.com/translator) for Node.js.
+A **simple** and **free** API for [Bing Translator](https://bing.com/translator) and [Microsoft Translator](https://learn.microsoft.com/azure/ai-services/translator/) for Node.js.
 
-## Install 
+## Install
 
 ```
 npm install bing-translate-api
 ```
 
 ## Usage
 
+### Microsoft Translator <sup>🆕</sup>
+
+Added since v4.0.0. More stable and powerful. Both free service and paid service are supported. Feel free to take a try!
+
+Read the [README](./src/met/README.md) for more details.
+
+### Bing Translator
+
 From auto-detected language to English:
 
 ```js

index.d.ts

@@ -1,6 +1,9 @@
 // AUTO-GENERATED. SEE scripts/index.tpl.d.ts FOR ORIGINAL TYPINGS
 
-import type { Agents } from 'got';
+import type {
+  Agents,
+  Options as GotOptions
+} from 'got';
 
 export interface TranslationResult {
   /**
@@ -60,7 +63,7 @@ export declare function translate(
   raw?: boolean,
   userAgent?: string,
   proxyAgents?: Agents
-): Promise<TranslationResult>;
+): Promise<TranslationResult | undefined>;
 
 export declare namespace lang {
   const LANGS: {
@@ -203,3 +206,190 @@ export declare namespace lang {
   function isSupported(lang: string): boolean;
   function isCorrectable(lang: string): boolean;
 }
+
+export declare namespace MET {
+  interface MetTranslateOptions {
+    translateOptions?: Record<string, object>;
+    authenticationHeaders?: Record<string, string>;
+    userAgent?: string;
+    gotOptions?: GotOptions
+  }
+
+  /**
+   * See https://learn.microsoft.com/azure/ai-services/translator/reference/v3-0-translate#response-body for full result structure
+   */
+  interface MetTranslationResult {
+    translations: {
+      text: string;
+      to: string;
+      sentLen?: {
+        srcSentLen: number[];
+        transSentLen: number[];
+      };
+      transliteration?: {
+        script: string;
+        text: string;
+      };
+      alignment?: object;
+    }[];
+    detectedLanguage?: {
+      language: string;
+      score: number;
+    }
+  }
+
+  /**
+   * @param text content to be translated
+   * @param source language code
+   * @param to target language code(s). `en` by default.
+   * @param options optional translate options
+   */
+  declare function translate(
+    text: string | string[],
+    from: string | null | undefined,
+    to: string | string[],
+    options?: MetTranslateOptions
+  ): Promise<MetTranslationResult[] | undefined>;
+
+  namespace lang {
+    const LANGS: {
+      'af': 'Afrikaans',
+      'am': 'Amharic',
+      'ar': 'Arabic',
+      'as': 'Assamese',
+      'az': 'Azerbaijani',
+      'ba': 'Bashkir',
+      'bg': 'Bulgarian',
+      'bho': 'Bhojpuri',
+      'bn': 'Bangla',
+      'bo': 'Tibetan',
+      'brx': 'Bodo',
+      'bs': 'Bosnian',
+      'ca': 'Catalan',
+      'cs': 'Czech',
+      'cy': 'Welsh',
+      'da': 'Danish',
+      'de': 'German',
+      'doi': 'Dogri',
+      'dsb': 'Lower Sorbian',
+      'dv': 'Divehi',
+      'el': 'Greek',
+      'en': 'English',
+      'es': 'Spanish',
+      'et': 'Estonian',
+      'eu': 'Basque',
+      'fa': 'Persian',
+      'fi': 'Finnish',
+      'fil': 'Filipino',
+      'fj': 'Fijian',
+      'fo': 'Faroese',
+      'fr': 'French',
+      'fr-CA': 'French (Canada)',
+      'ga': 'Irish',
+      'gl': 'Galician',
+      'gom': 'Konkani',
+      'gu': 'Gujarati',
+      'ha': 'Hausa',
+      'he': 'Hebrew',
+      'hi': 'Hindi',
+      'hne': 'Chhattisgarhi',
+      'hr': 'Croatian',
+      'hsb': 'Upper Sorbian',
+      'ht': 'Haitian Creole',
+      'hu': 'Hungarian',
+      'hy': 'Armenian',
+      'id': 'Indonesian',
+      'ig': 'Igbo',
+      'ikt': 'Inuinnaqtun',
+      'is': 'Icelandic',
+      'it': 'Italian',
+      'iu': 'Inuktitut',
+      'iu-Latn': 'Inuktitut (Latin)',
+      'ja': 'Japanese',
+      'ka': 'Georgian',
+      'kk': 'Kazakh',
+      'km': 'Khmer',
+      'kmr': 'Kurdish (Northern)',
+      'kn': 'Kannada',
+      'ko': 'Korean',
+      'ks': 'Kashmiri',
+      'ku': 'Kurdish (Central)',
+      'ky': 'Kyrgyz',
+      'ln': 'Lingala',
+      'lo': 'Lao',
+      'lt': 'Lithuanian',
+      'lug': 'Ganda',
+      'lv': 'Latvian',
+      'lzh': 'Chinese (Literary)',
+      'mai': 'Maithili',
+      'mg': 'Malagasy',
+      'mi': 'Māori',
+      'mk': 'Macedonian',
+      'ml': 'Malayalam',
+      'mn-Cyrl': 'Mongolian (Cyrillic)',
+      'mn-Mong': 'Mongolian (Traditional)',
+      'mni': 'Manipuri',
+      'mr': 'Marathi',
+      'ms': 'Malay',
+      'mt': 'Maltese',
+      'mww': 'Hmong Daw',
+      'my': 'Myanmar (Burmese)',
+      'nb': 'Norwegian',
+      'ne': 'Nepali',
+      'nl': 'Dutch',
+      'nso': 'Sesotho sa Leboa',
+      'nya': 'Nyanja',
+      'or': 'Odia',
+      'otq': 'Querétaro Otomi',
+      'pa': 'Punjabi',
+      'pl': 'Polish',
+      'prs': 'Dari',
+      'ps': 'Pashto',
+      'pt': 'Portuguese (Brazil)',
+      'pt-PT': 'Portuguese (Portugal)',
+      'ro': 'Romanian',
+      'ru': 'Russian',
+      'run': 'Rundi',
+      'rw': 'Kinyarwanda',
+      'sd': 'Sindhi',
+      'si': 'Sinhala',
+      'sk': 'Slovak',
+      'sl': 'Slovenian',
+      'sm': 'Samoan',
+      'sn': 'Shona',
+      'so': 'Somali',
+      'sq': 'Albanian',
+      'sr-Cyrl': 'Serbian (Cyrillic)',
+      'sr-Latn': 'Serbian (Latin)',
+      'st': 'Sesotho',
+      'sv': 'Swedish',
+      'sw': 'Swahili',
+      'ta': 'Tamil',
+      'te': 'Telugu',
+      'th': 'Thai',
+      'ti': 'Tigrinya',
+      'tk': 'Turkmen',
+      'tlh-Latn': 'Klingon (Latin)',
+      'tlh-Piqd': 'Klingon (pIqaD)',
+      'tn': 'Setswana',
+      'to': 'Tongan',
+      'tr': 'Turkish',
+      'tt': 'Tatar',
+      'ty': 'Tahitian',
+      'ug': 'Uyghur',
+      'uk': 'Ukrainian',
+      'ur': 'Urdu',
+      'uz': 'Uzbek (Latin)',
+      'vi': 'Vietnamese',
+      'xh': 'Xhosa',
+      'yo': 'Yoruba',
+      'yua': 'Yucatec Maya',
+      'yue': 'Cantonese (Traditional)',
+      'zh-Hans': 'Chinese Simplified',
+      'zh-Hant': 'Chinese Traditional',
+      'zu': 'Zulu'
+    };
+    function getLangCode(lang: string): string | undefined;
+    function isSupported(lang: string): boolean;
+  }
+}

package-lock.json

@@ -1,21 +1,23 @@
 {
   "name": "bing-translate-api",
-  "version": "3.0.1",
-  "description": "A simple and free API for Bing Translator for Node.js",
+  "version": "4.0.0",
+  "description": "A simple and free API for Bing & Microsoft Translator for Node.js",
   "main": "src/index.js",
   "typings": "index.d.ts",
   "scripts": {
-    "test": "node test/index.js && node test/lang.js",
+    "test": "node test/index.js && node test/lang.js && node test/met.js",
     "gen:config": "node scripts/generate-config.js"
   },
   "keywords": [
     "bing",
+    "microsoft",
     "translator",
     "api",
     "javascript",
     "free",
     "node",
-    "translate"
+    "translate",
+    "azure"
   ],
   "files": [
     "src",

package.json

@@ -1,3 +1,6 @@
+/**
+ * @type {import('got').Got}
+ */
 const got = require('got')
 const cheerio = require('cheerio')
 const fs = require('node:fs')
@@ -76,6 +79,28 @@ const DEFAULT_USER_AGENT = 'Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKi
   console.log('✔️ Generated language map\n', langMap)
   console.log()
 
+  // Languages supported by MET mode (usually it's the same with bing translator)
+  const { translation: metTranslationLanguages } = await got('https://api.cognitive.microsofttranslator.com/languages', {
+    searchParams: {
+      'api-version': '3.0',
+      scope: 'translation'
+    },
+    headers: {
+      'Accept-Language': 'en-US,en',
+      'User-Agent': DEFAULT_USER_AGENT
+    }
+  }).json()
+  const metLangMap = Object.entries(metTranslationLanguages)
+    .reduce((langCodeMap, [langCode, langItem]) => (langCodeMap[langCode] = langItem.name, langCodeMap), {})
+  fs.writeFileSync(
+    path.resolve(__dirname, '../src/met/lang.json'),
+    JSON.stringify(metLangMap, null, 2),
+    { charset: 'utf-8' }
+  )
+  console.log()
+  console.log('✔️ Generated language map (MET mode)\n', metLangMap)
+  console.log()
+
   // update ts definition
   require('./generate-dts')
 })()

scripts/generate-config.js

@@ -1,6 +1,7 @@
 const fs = require('node:fs')
 const path = require('node:path')
 const { LANGS } = require('../src/lang')
+const { LANGS: MET_LANGS } = require('../src/met/lang')
 
 // update ts definition
 const typingsTpl = fs.readFileSync(path.resolve(__dirname, './index.tpl.d.ts'), 'utf-8')
@@ -12,7 +13,12 @@ fs.writeFileSync(
     JSON.stringify(LANGS, null, 4)
       .replace('}', `${' '.repeat(2)}}`)
       .replace(/"/g, '\'')
-    ),
+  ).replace(
+    '__LANG_MAP__',
+    JSON.stringify(MET_LANGS, null, 6)
+      .replace('}', `${' '.repeat(4)}}`)
+      .replace(/"/g, '\'')
+  ),
   { charset: 'utf-8' }
 )