{"id":13062,"library":"deepl-node","title":"DeepL Node.js Client Library","description":"The `deepl-node` library is the official Node.js client for interacting with the DeepL API, offering high-quality machine translation services for text and documents. Currently at version 1.26.0, the library receives regular updates, often incorporating new DeepL API features such as support for translation memories, comprehensive style rule management (CRUD operations), custom translation instructions, and expanded language code support. Its release cadence is feature-driven, ensuring timely access to the latest API capabilities. Key differentiators include its direct integration with DeepL's proprietary translation technology, official endorsement, and extensive support for API functions, making it a robust choice for developers building translation-reliant applications. It supports modern Node.js environments, ships with TypeScript types, and facilitates advanced translation configurations like tag handling and custom request parameters.","status":"active","version":"1.26.0","language":"javascript","source_language":"en","source_url":"git://github.com/DeepLcom/deepl-node","tags":["javascript","deepl","translator","api","typescript"],"install":[{"cmd":"npm install deepl-node","lang":"bash","label":"npm"},{"cmd":"yarn add deepl-node","lang":"bash","label":"yarn"},{"cmd":"pnpm add deepl-node","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"HTTP client for making API requests, periodically updated for security fixes.","package":"axios","optional":false}],"imports":[{"note":"The library primarily uses a wildcard import pattern (`* as deepl`) to expose its API, not named exports for the main client class.","wrong":"import { DeepLClient } from 'deepl-node';","symbol":"DeepLClient","correct":"import * as deepl from 'deepl-node'; const client = new deepl.DeepLClient(authKey);"},{"note":"For CommonJS environments, the entire module object is typically required, and then the DeepLClient constructor is accessed as a property of that object.","wrong":"const { DeepLClient } = require('deepl-node');","symbol":"DeepLClient (CommonJS)","correct":"const deepl = require('deepl-node'); const client = new deepl.DeepLClient(authKey);"},{"note":"Type imports also follow the wildcard import pattern, requiring access via the `deepl.` namespace.","wrong":"import { TargetLanguageCode } from 'deepl-node';","symbol":"TargetLanguageCode","correct":"import * as deepl from 'deepl-node'; const lang: deepl.TargetLanguageCode = 'fr';"}],"quickstart":{"code":"import * as deepl from 'deepl-node';\n\nasync function main() {\n    const authKey = process.env.DEEPL_AUTH_KEY ?? 'YOUR_DEEPL_AUTH_KEY'; // It is recommended to use environment variables\n    if (authKey === 'YOUR_DEEPL_AUTH_KEY' || !authKey) {\n        console.error('Please set the DEEPL_AUTH_KEY environment variable or replace the placeholder.');\n        process.exit(1);\n    }\n\n    const deeplClient = new deepl.DeepLClient(authKey);\n\n    try {\n        // Translate a single text\n        const resultSingle = await deeplClient.translateText('Hello, world!', null, 'fr');\n        console.log(`Single translation: ${resultSingle.text}`); // Bonjour, le monde !\n\n        // Translate multiple texts\n        const targetLang: deepl.TargetLanguageCode = 'es';\n        const textsToTranslate = ['How are you?', 'Nice to meet you!'];\n        const resultsMultiple = await deeplClient.translateText(\n            textsToTranslate,\n            null, // Auto-detect source language\n            targetLang,\n            { tagHandling: 'xml', ignoreTags: ['em'] } // Example options\n        );\n        resultsMultiple.map((result: deepl.TextResult) => {\n            console.log(`Multiple translation: ${result.text}`);\n        });\n\n        // List available translation memories (example of another API call)\n        const tms = await deeplClient.listTranslationMemories();\n        console.log(`Found ${tms.length} translation memories.`);\n\n    } catch (error) {\n        if (error instanceof deepl.DeepLError) {\n            console.error(`DeepL API Error: ${error.message} (HTTP Status: ${error.statusCode})`);\n        } else {\n            console.error(`An unexpected error occurred: ${error}`);\n        }\n    }\n}\n\nmain();","lang":"typescript","description":"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."},"warnings":[{"fix":"Upgrade your Node.js runtime to version 20, 22, 24, or later. Refer to the official Node.js release schedule for supported versions.","message":"Support 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.","severity":"breaking","affected_versions":">=1.20.0"},{"fix":"Avoid setting `modelType: 'latency_optimized'` when `customInstructions` are provided. If latency is critical, consider whether custom instructions are strictly necessary for that specific translation.","message":"Using 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.","severity":"gotcha","affected_versions":">=1.23.0"},{"fix":"Upgrade to `deepl-node` version 1.20.0 or later to ensure document minification and deminification correctly preserve translated content.","message":"Previous 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.","severity":"breaking","affected_versions":"<1.20.0"},{"fix":"Ensure 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.","message":"The `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.","severity":"breaking","affected_versions":"<1.17.3, >=1.17.3 <1.26.0"},{"fix":"If 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.","message":"The `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`.","severity":"gotcha","affected_versions":"<1.24.0"}],"env_vars":null,"last_verified":"2026-04-19T00:00:00.000Z","next_check":"2026-07-18T00:00:00.000Z","problems":[{"fix":"For 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);`.","cause":"Attempting to destructure `DeepLClient` from a CommonJS `require()` or using a named import style with ESM `import`.","error":"TypeError: deepl.DeepLClient is not a constructor"},{"fix":"Verify 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.","cause":"The provided DeepL authentication key is either incorrect, expired, or has not been activated.","error":"Error: Invalid authentication key"},{"fix":"Remove the `modelType: 'latency_optimized'` option when `customInstructions` are present in your `translateText()` call. The API will default to `quality_optimized`.","cause":"You are attempting to use `customInstructions` with the `latency_optimized` model type, which is explicitly disallowed by the DeepL API.","error":"Error: The requested modelType 'latency_optimized' is not compatible with 'custom_instructions'"}],"ecosystem":"npm","meta_description":null,"install_score":null,"install_tag":null,"quickstart_score":null,"quickstart_tag":null,"pypi_latest":null,"cli_name":""}