gillescoolen/deepl-client

A client for the DeepL Translation API written in TypeScript.

Archived due to the DeepL team releasing an official Node client.

See https://github.com/DeepLcom/deepl-node for the official client. Thanks to everyone contributing over the years. Bye! 👋

DeepL Client

See the official documentation for the available parameters.

You can make a simple request using the following code.

const params: TranslationParameters = {
  auth_key: your.authentication.key,
  text: 'This is a sentence.',
  target_lang: Language.French,
};

await translate(params);

Which will return a TranslationResponse, containing an array with the translation, and the detected source language.

{
  "translations": [
    {
      "detected_source_language": "EN",
      "text": "C'est une phrase."
    }
  ]
}

Translate Multiple

To translate an array of text, you can use the translateMultiple function.

const params: TranslationMultipleParameters = {
  auth_key: your.authentication.key,
  target_lang: Language.French,
};

const text = ['This is a sentence.', 'This is another sentence.'].

await translateMultiple(params, text);

Which will return the same TranslationResponse, except with more entries.

{
  "translations": [
    {
      "detected_source_language": "EN",
      "text": "C'est une phrase."
    },
    {
      "detected_source_language": "EN",
      "text": "C'est une autre phrase."
    }
  ]
}

Usage

To see the usage statistics linked to your authorization key, you can use the usage function.

const params: UsageParameters = {
  auth_key: your.authentication.key
};

await usage(params);

Which will return a UsageResponse, containing the used character count and the set characterl limit.

{
  "character_count":398,
  "character_limit":5000000
}

Missing something? Don't hesitate to open an issue or pull request!

Contributing

Install the dependencies using npm ci.
Run the linter with npm run lint.
Copy the env.example file and add a valid API key.
Run the tests with npm t.

deepl-client's Issues

Add support for passing `node-fetch` options

The Deepl API after 10-15 translations hangs me for a while, sometimes even 5 minutes... I'd like to use AbortController and implement a retry/timeout feature for myself. (Or it could be part of the client as well).

Support translating multiple texts

I am currently building an on the fly translation for an api which may have a lot of separate text blocks to translate. This does not scale very well if I have to create a separate translation promise for each text block. A suitable alternative could be to use the Large volumes of text feature.

This can be quickly achieved by changing the type definition for TranslationParameters::text to a union type of string | string[]. I would be ready to create a pull request for such a change if you are interested.

Thanks for the awesome package.

Deepl is offering a free development api, put an option to use in API.

https://www.deepl.com/pro#developer

Version 1.0.5 is not available from npm

Please, publish the latest version to npm

Add new European languages

Add the new languages as described in the blog post.

(The site is down for me at the moment which is why I made this issue instead of doing it immediately.)

Add formality feature to list of parameters

From Deepl API
https://www.deepl.com/docs-api/translating-text/request/

formality	Optional	Sets whether the translated text should lean towards formal or informal language. This feature currently only works for "DE (German)", "NL (Dutch)" and "PL (Polish)" as target language.Possible options are: "default" (default)"more" - for a more formal language"less" - for a more informal language

Integration of method for recieving usage information

Would it be possible to implement a method to get the usage information from deepl?

https://api.deepl.com/v2/usage?auth_key=[Auth_key]

This returns a json with translated characters and the defined limit:

{
"character_count": 1365380,
"character_limit": 4000000
}

Vanilla JS Usage

Write a guide explaining how to use the package in vanilla JavaScript.

type "module" causes errors (with typescript?)

Since the new 1.0.13 release you use

{ "type": "module" }

in your package.json.
this breaks compatibility with our typescript app.

Here is the error

14:05:27 - Found 0 errors. Watching for file changes.
node:internal/modules/cjs/loader:1119
      throw new ERR_REQUIRE_ESM(filename, parentPath, packageJsonPath);
      ^

Error [ERR_REQUIRE_ESM]: Must use import to load ES Module: /home/koriwi/Documents/maet-server/node_modules/deepl-client/dist/index.js
require() of ES modules is not supported.
require() of /home/koriwi/Documents/maet-server/node_modules/deepl-client/dist/index.js from /home/koriwi/Documents/maet-server/dist/lib/consts.js is an ES module file as it is a .js file whose nearest parent package.json contains "type": "module" which defines all .js files in that package scope as ES modules.
Instead rename index.js to end in .cjs, change the requiring code to use import(), or remove "type": "module" from /home/koriwi/Documents/maet-server/node_modules/deepl-client/package.json.

here is our tsconfig.json

{
  "compilerOptions": {
    "target": "ES2019",
    "incremental": true,
    "moduleResolution": "node",
    "module": "commonjs",
    "sourceMap": true,
    "rootDir": "./src",
    "noImplicitAny": true,
    "outDir": "dist",
    "lib": ["esnext", "dom"],
    "typeRoots": ["./node_modules/@types", "./src/definitions"],
    "noUnusedLocals": true,
    "esModuleInterop": true,
    "downlevelIteration": true,
    "strictNullChecks": true,
    "tsBuildInfoFile": "./dist/tsconfig.tsbuildinfo",
    "strict": true
  }
}

Versions:

• Node: v15.2.1
• Typescript: 3.7.5

Remove .git folder from npm package

Repeatedly performing npm-install fails with EISGIT: Appears to be a git repo or submodule.
So, please, update the npm package and remove .git folder from it

More expressive errors

Please note that this is a lower priority feature request since there are other ways to work around this

It is currently difficult to find out the real reason a request failed since the library always returns the same error upon failure. It would be nice if the errors could correspond to the request errors from the deepl-api along with the error codes.

Error for wrong auth key is not really propagated

If you are using a wrong api key (by accident, license stopped...), the error is not really propagated by the library.

Sample:

curl -I "https://api.deepl.com/v2/translate"

results in

HTTP/2 403 
server: nginx
date: Wed, 01 Jul 2020 19:40:31 GMT
content-length: 0
access-control-allow-origin: *

What i get with the following node snippet

let d= require("deepl-client");

d.translate(
  {auth_key: "wrong", 
   target_lang: "de", 
   text: "Hello"} )
.then( result => {console.dir("then branch"); console.dir(result);})
.catch( err    =>  {console.dir("catch branch"); console.dir(err) });

results in

FetchError: invalid json response body at https://api.deepl.com/v2/translate?auth_key=wron&target_lang=de&text=Hello reason: Unexpected end of JSON input
    at /Users/TheFive.osm/development/osmbc/node_modules/node-fetch/lib/index.js:272:32
    at processTicksAndRejections (internal/process/task_queues.js:93:5) {
  message: 'invalid json response body at https://api.deepl.com/v2/translate?auth_key=wron&target_lang=de&text=Hello reason: Unexpected end of JSON input',
  type: 'invalid-json'
}
'then branch'
undefined

So the error is put to console, and the Library call does not return an error nor a result

Typescript in RunKit?

Is typescript so prevalent that a non-typescript version isnt also made available?