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.
DeepLClient
✓ import * as deepl from 'deepl-node'; const client = new deepl.DeepLClient(authKey);
✗ import { DeepLClient } from 'deepl-node';
The library primarily uses a wildcard import pattern (`* as deepl`) to expose its API, not named exports for the main client class.
DeepLClient (CommonJS)
✓ const deepl = require('deepl-node'); const client = new deepl.DeepLClient(authKey);
✗ const { DeepLClient } = require('deepl-node');
For CommonJS environments, the entire module object is typically required, and then the DeepLClient constructor is accessed as a property of that object.
TargetLanguageCode
✓ import * as deepl from 'deepl-node'; const lang: deepl.TargetLanguageCode = 'fr';
✗ import { TargetLanguageCode } from 'deepl-node';
Type imports also follow the wildcard import pattern, requiring access via the `deepl.` namespace.
Demonstrates initializing the DeepL client, translating single and multiple texts, using TypeScript types, and handling potential errors. It also shows an example of listing translation memories.
import * as deepl from 'deepl-node';
async function main() {
const authKey = process.env.DEEPL_AUTH_KEY ?? 'YOUR_DEEPL_AUTH_KEY'; // It is recommended to use environment variables
if (authKey === 'YOUR_DEEPL_AUTH_KEY' || !authKey) {
console.error('Please set the DEEPL_AUTH_KEY environment variable or replace the placeholder.');
process.exit(1);
}
const deeplClient = new deepl.DeepLClient(authKey);
try {
// Translate a single text
const resultSingle = await deeplClient.translateText('Hello, world!', null, 'fr');
console.log(`Single translation: ${resultSingle.text}`); // Bonjour, le monde !
// Translate multiple texts
const targetLang: deepl.TargetLanguageCode = 'es';
const textsToTranslate = ['How are you?', 'Nice to meet you!'];
const resultsMultiple = await deeplClient.translateText(
textsToTranslate,
null, // Auto-detect source language
targetLang,
{ tagHandling: 'xml', ignoreTags: ['em'] } // Example options
);
resultsMultiple.map((result: deepl.TextResult) => {
console.log(`Multiple translation: ${result.text}`);
});
// List available translation memories (example of another API call)
const tms = await deeplClient.listTranslationMemories();
console.log(`Found ${tms.length} translation memories.`);
} catch (error) {
if (error instanceof deepl.DeepLError) {
console.error(`DeepL API Error: ${error.message} (HTTP Status: ${error.statusCode})`);
} else {
console.error(`An unexpected error occurred: ${error}`);
}
}
}
main();
Debug
Known issues
breakingSupport for Node.js versions 12, 14, 16, 17, and 18 will be dropped in 2025. Applications running on these End-of-Life Node.js versions may encounter compatibility issues or cease to function with future library updates.fixUpgrade your Node.js runtime to version 20, 22, 24, or later. Refer to the official Node.js release schedule for supported versions.
affects: >=1.20.0
gotchaUsing the `customInstructions` parameter in `translateText()` will automatically default the translation model type to `quality_optimized`. Any requests combining `customInstructions` with an explicit `latency_optimized` model type will be rejected by the API.fixAvoid setting `modelType: 'latency_optimized'` when `customInstructions` are provided. If latency is critical, consider whether custom instructions are strictly necessary for that specific translation.
affects: >=1.23.0
breakingPrevious versions (prior to 1.20.0) had a bug where document translations with minification enabled could result in the loss of translated content during the deminify process.fixUpgrade to `deepl-node` version 1.20.0 or later to ensure document minification and deminification correctly preserve translated content.
affects: <1.20.0
breakingThe `axios` dependency has been updated in response to security vulnerabilities (CVE-2025-62718 in v1.26.0, GHSA-jr5f-v2jv-69x6 in v1.17.3). Older versions of `deepl-node` might use vulnerable `axios` versions.fixEnsure you are using `deepl-node` version 1.26.0 or newer to benefit from the latest `axios` security patches. Regularly update dependencies to mitigate potential supply chain risks.
affects: <1.17.3, >=1.17.3 <1.26.0
gotchaThe `tagHandlingVersion` parameter was introduced in v1.24.0, allowing selection between `v1` and `v2` of the tag handling algorithm. Older versions will implicitly use `v1`.fixIf you require the improved tag handling features of `v2`, update to `deepl-node` v1.24.0 or later and explicitly set `tagHandlingVersion: 'v2'` in your `translateText()` calls.
affects: <1.24.0
Errors
Common errors & fixes
TypeError: deepl.DeepLClient is not a constructor
Attempting to destructure `DeepLClient` from a CommonJS `require()` or using a named import style with ESM `import`.
fixFor CommonJS, use `const deepl = require('deepl-node'); const client = new deepl.DeepLClient(authKey);`. For ESM, use `import * as deepl from 'deepl-node'; const client = new deepl.DeepLClient(authKey);`. Error: Invalid authentication key
The provided DeepL authentication key is either incorrect, expired, or has not been activated.
fixVerify your authentication key in your DeepL Pro Account dashboard. Ensure there are no typos, leading/trailing spaces, or unescaped characters. Make sure your account is active.
Error: The requested modelType 'latency_optimized' is not compatible with 'custom_instructions'
You are attempting to use `customInstructions` with the `latency_optimized` model type, which is explicitly disallowed by the DeepL API.
fixRemove the `modelType: 'latency_optimized'` option when `customInstructions` are present in your `translateText()` call. The API will default to `quality_optimized`.
Audit
Dependencies
axiosrequiredHTTP client for making API requests, periodically updated for security fixes.