Install & Compatibility
Where this runs
tested against v? · npm install
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
muslnode 18–226 runs
build_error
glibcnode 18–226 runs
build_error
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
translate
✓ import { translate } from 'bing-translate-api';
✗ const { translate } = require('bing-translate-api');
While CommonJS `require` still works, ESM `import` is the preferred modern syntax, especially given the TypeScript types included.
translate (MET Mode)
✓ import { translate } from 'bing-translate-api/met'; // For Microsoft Translator mode
import { MET } from 'bing-translate-api/met'; // Or use the MET constant
✗ import { translate } from 'bing-translate-api'; // This is for Bing Translator (legacy/EPT mode)
Since v4.0.0, the more stable Microsoft Translator (MET) mode is available via a separate import path. Ensure you import from `bing-translate-api/met` to use this mode.
TranslateResult
✓ import type { TranslateResult } from 'bing-translate-api';
For TypeScript users, import the `TranslateResult` type to ensure type safety when handling translation responses. The structure includes `translation`, `language`, and optionally `feminineTranslation`/`masculineTranslation`.
Demonstrates basic text translation using `translate` with auto-detection, explicit language codes, and optional text correction. Includes comments for using the MET mode.
import { translate } from 'bing-translate-api';
async function performTranslation() {
try {
// Translate 'Hello world' from English to Spanish
const resultEnToEs = await translate('Hello world', 'en', 'es');
console.log('English to Spanish:', resultEnToEs.translation);
// Translate '你好' (Ni hao) from auto-detected Chinese to English
const resultZhToEn = await translate('你好', null, 'en');
console.log('Chinese to English:', resultZhToEn.translation);
// Translate with correction enabled (limited to 50 characters for correction)
const resultCorrect = await translate('helo there', 'en', 'fr', true);
console.log('Corrected and translated:', resultCorrect.translation);
// Example of using the MET mode (Microsoft Translator) for potentially better stability
// import { translate as translateMet } from 'bing-translate-api/met';
// const resultMet = await translateMet('Hello from MET mode', 'en', 'de');
// console.log('MET mode translation:', resultMet.translation);
} catch (err) {
console.error('Translation error:', err);
}
}
performTranslation();
Debug
Known issues
breakingVersion 4.0.0 introduced a new, more stable Microsoft Translator (MET) mode. While the original Bing Translator mode is still accessible, developers are encouraged to migrate to MET mode for better reliability. The MET mode has a distinct import path (`bing-translate-api/met`).fixFor new projects or enhanced stability, switch to `import { translate } from 'bing-translate-api/met';` instead of the default `bing-translate-api` import for Microsoft Translator mode. affects: >=4.0.0
breakingVersion 3.0.0 introduced an experimental EPT mode and removed `cookie` from HTTP requests, which previously might have been used for maintaining session state. This version also changed the default `maxTextLen` for translation.fixReview existing code for `cookie` usage (which is no longer passed). Be aware of the `maxTextLen` changes, especially for EPT mode which has a 3000 character limit, and ensure language support aligns with the `eptLangs` list to avoid falling back to legacy mode and potential 429 errors.
affects: >=3.0.0
gotchaText length limits vary significantly based on the translation mode and geographical region. The default is 1000 characters, but can be up to 5000 in China, and is specifically 3000 characters in EPT mode.fixAlways validate input text length before sending to the API. If consistently dealing with longer texts, consider breaking them into smaller chunks or implementing custom logic to handle the varying limits per mode.
affects: >=1.0.0
gotchaThe EPT mode (introduced in v3.0.0) and the correction service (since v1.1.0) have specific language support limitations. Using unsupported languages in EPT mode will cause a fallback to the legacy mode, which is more prone to rate limiting (429 errors). The correction service is limited to 50 characters and a specific list of languages.fixConsult `src/lang.json` and `src/config.json#eptLangs` for supported languages in EPT mode. For correction, ensure text is under 50 characters and in a supported language. Implement error handling to gracefully manage fallback scenarios or unsupported language attempts.
affects: >=3.0.0 (EPT), >=1.1.0 (Correction)
deprecatedThe `maxTextLen` was updated from 1000 to 5000 in v2.10.0, but then adjusted again for EPT mode in v3.0.0 to 3000, and the default reverted to 1000 for non-China usage. Relying on a fixed large `maxTextLen` across all modes and regions can lead to issues.fixDynamically determine or explicitly check the `maxTextLen` based on the chosen translation mode (legacy, EPT, MET) and target region to avoid exceeding limits.
affects: >=2.10.0
Errors
Common errors & fixes
HTTP 429 Too Many Requests
Frequent requests exceeding Bing's rate limits, especially common when using the older Bing Translator mode or EPT mode with unsupported languages causing a fallback to legacy.
fixImplement exponential backoff and retry logic. Consider switching to the more stable Microsoft Translator (MET) mode (`bing-translate-api/met`) if possible, or introduce delays between requests. Ensure languages used with EPT mode are within its supported list.
TS(1038): A 'declare' modifier cannot be used in an already ambient context.
Incorrect TypeScript type declaration syntax, specifically nested `declare` modifiers.
fixUpgrade to version `4.0.1` or later, as this issue was fixed in `v4.0.1`.
TypeError: Cannot read properties of undefined (reading 'detectedLang')
The `detectedLang` property was sometimes missing from the API response.
fixUpgrade to version `4.0.2` or later, as this specific error was addressed in `v4.0.2` by avoiding throwing an error when `detectedLang` is absent.
Audit
Dependencies
No dependency data recorded yet.