deepl_dart 1.0.1 icon indicating copy to clipboard operation
deepl_dart: ^1.0.1 copied to clipboard

Dart library for the DeepL language translation API.

deepl_dart #

Dart Analyze & Test codecov

This package is maintained by volunteers but is not a supported DeepL product and not maintained by DeepL SE. Issues here are answered by maintainers and other community members on GitHub on a best-effort basis.

This package is heavily inspired by the official Node.js Client Library for the DeepL API:

The DeepL API is a language translation API that allows other computer programs to send texts and documents to DeepL's servers and receive high-quality translations. This opens a whole universe of opportunities for developers: any translation product you can imagine can now be built on top of DeepL's best-in-class translation technology.

The DeepL [Dart] library offers a convenient way for applications written for [Dart and Flutter] to interact with the DeepL API. We intend to support all API functions with the library, though support for new features may be added to the library after they’re added to the API. ~ DeepL

Getting an authentication key #

To use the package, you'll need an API authentication key. To get a key, please create an account here. You can translate up to 500,000characters/month for free.

Roadmap #

Installation #

In the dependencies: section of your pubspec.yaml, add the following line:

dependencies:
  deepl_dart: <latest_version>

Usage #

Import the package and construct a Translator. The required argument authKey is a string containing your API authentication key as found in your DeepL Pro Account.

Be careful not to expose your key, for example when sharing source code.

An example using async/await:

import 'package:deepl_dart/deepl_dart.dart';

void main() async {
  // Construct Translator
  Translator translator = Translator(authKey: '<your_auth_key>');

  // Translate text
  TextResult result =
      await translator.translateTextSingular('Hello World', 'de');
  print(result);

  // Translate list of texts
  List<TextResult> results =
      await translator.translateTextList(['Hello World', 'Hola Mundo'], 'de');
  print(results);
}

Translator Object #

All requests to the DeepL API go via a Translator object. A auth_key from DeepL is required to send requests. Pass it via Translator constructor:

Translator translator = Translator(authKey: '<your_auth_key>');

This example is for demonstration purposes only. In production code, the authentication key should not be hard-coded, but instead fetched from a configuration file or environment variable.

Add further arguments to the constructor:

Translator translator =   Translator(
    authKey: '<your_auth_key>',
    headers: {'My-Header-Key': 'my header value'},
    serverUrl: 'https://alternative.deepl.api.server.url',
    maxRetries: 42,
  );

Translate Text #

The basic text translation takes one or more texts and a target language to return the translated text. DeepL detects the source language automatically.

// Translate a single text
TextResult result =
    await translator.translateTextSingular('Hello World', 'de');

// Translate multiple texts
List<TextResult> results =
    await translator.translateTextList(['Hello World', 'Hola Mundo'], 'de');

Optionally you can pass the source language as well.

TextResult result = await translator
    .translateTextSingular('Hello World', 'de', sourceLang: 'en');

If you unsure which languages are supported you can request them.

  List<Language> sourceLangs = await translator.getSourceLanguages();
  List<Language> targetLangs = await translator.getTargetLanguages();

You can pass a TranslateTextOptions object to configure the translation.

TextResult result = await translator.translateTextSingular(
  'Hello World',
  'de',
  options: TranslateTextOptions(
      splitSentences: 'on',
      formality: 'less',
      glossaryId: myGlossary.glossaryId,
  ),
);

Translate Documents #

DeepL also supports the translation of documents. At the moment of writing the following file types are supported:

  • .docx
  • .pptx
  • .pdf
  • .txt

The document translation method internally uploads given input file, waits for the translation to finish and downloads the file into the given output file. As well as with the text translation a target language is required.

DocumentStatus status = await translator.translateDocument(
    File('<input_file_path>'), File('<output_file_path>'), 'de');

Optionally you can pass the source language as well.

DocumentStatus status = await translator.translateDocument(
    File('<input_file_path>'), File('<output_file_path>'), 'de',
    sourceLang: 'en');

You can pass a DocumentTranslateOptions object to configure the translation.

DocumentStatus status = await translator.translateDocument(
  File('<input_file_path>'),
  File('<output_file_path>'),
  'de',
  options: DocumentTranslateOptions(
    formality: 'less',
    glossaryId: myGlossary.glossaryId,
  ),
);

Manage Glossaries #

DeepL supports glossaries to manage custom translations. To use them you have to create one.

GlossaryInfo glossaryInfo = await translator.createGlossary(
  name: 'my glossary',
  sourceLang: 'en',
  targetLang: 'de',
  entries: GlossaryEntries(entries: {
    'hello': 'hi',
    'world': 'erde',
  }),
);

Not all languages are supported. You can check the possible language pairs.

  List<GlossaryLanguagePair> languagePairs =
      await translator.getGlossaryLanguagePairs();

Once you created a glossary you can use it for translations as part of the TranslateTextOptions and the DocumentTranslateOptions (see above).

To get all your glossaries or a specific one, you can request them.

// List glossaries
List<GlossaryInfo> glossaryList = await translator.listGlossaries();

// Get glossary info
GlossaryInfo glossaryInfo = await translator.getGlossary(glossaryInfo.glossaryId);

To get the entries of a glossary, you have to request them seperately.

GlossaryEntries glossaryEntries =
      await translator.getGlossaryEntries(glossaryId: '<glossary_info_if>');

// with a glossary info object
GlossaryEntries glossaryEntries =
    await translator.getGlossaryEntries(glossaryInfo: glossaryInfo);

Lastly, you can delete a glossary.

await translator.deleteGlossary(glossaryId: glossaryInfo.glossaryId);

Translation Usage #

Find out more about the used translations and your limits.

Usage usage = await translator.getUsage();

Additional information #

For more information, check out the official Node.js Client Library for the DeepL API and the DeepL API Docs.

4
likes
120
pub points
33%
popularity

Publisher

verified publisher iconkpelz.eu

Dart library for the DeepL language translation API.

Repository (GitHub)
View/report issues

Documentation

API reference

License

Icon for licenses.MIT (LICENSE)

Dependencies

collection, http, json_annotation

More

Packages that depend on deepl_dart