deeprl

Access the DeepL translation engine through a quick and reliable interface. We aim to provide the full suite of tools DeepL offers. See the DeepL API docs for detailed resources.

Note:

This crate uses a blocking http client, and as such is only suitable for use in synchronous (blocking) applications. If you intend to use the library functions in an async app, there is a crate for that.

Quickstart

Create a new client with a valid API token to access the associated methods. For instance, you may wish to translate a simple text string to some target language.

```rust use deeprl::{DeepL, Language, TextOptions};

let key = std::env::var("DEEPLAPIKEY").unwrap(); let dl = DeepL::new(&key);

// Translate 'good morning' to German let opt = TextOptions::new(Language::DE);

let text = vec![ "good morning".to_string(), ];

let result = dl.translate(opt, text).unwrap(); assert!(!result.translations.is_empty());

let translation = &result.translations[0]; assert_eq!(translation.text, "Guten Morgen"); ```

As a helpful sanity check, make sure you're able to return account usage statistics.

```rust use deeprl::DeepL;

let dl = DeepL::new( &std::env::var("DEEPLAPIKEY").unwrap() );

let usage = dl.usage().unwrap(); assert!(usage.character_limit > 0);

let count = usage.charactercount; let limit = usage.characterlimit; println!("Used: {count}/{limit}"); // Used: 42/500000 ```

Walkthrough

Contents: - Configuration - Errors - Get available languages - Translate text options - Tag handling - Translate documents - Manage glossaries

Configuration

The library supports a number of configuration options, one of which is the ability to swap out the default client for a new instance of reqwest::blocking::Client.

As before, we create a new instance of DeepL, but this time we declare it mut. Then we call client on the object and pass in our custom client.

```rust let mut dl = DeepL::new( &std::env::var("DEEPLAPIKEY").unwrap() );

let client = reqwest::blocking::Client::builder() .timeout(std::time::Duration::from_secs(21)) .build() .unwrap();

dl.client(client); ```

We support sending a custom user agent along with requests. So for instance if you're using this library in another application, say My App v1.2.3, you can set the app name and version using set_app_info. ```rust // snip--

dl.setappinfo( "my-app/1.2.3".to_string() ); ```

Errors

Errors are encapsulated in the Error enum whose variants may be one of: - Client: A generic client-side error - Server: An error sent by the server - Deserialize: An error occurred while deserializing the response - InvalidRequest: Error sending an http request - InvalidResponse: Error parsing the response - InvalidLanguage: Error matching a user-supplied string to a Language

The library functions we'll look at below are all methods on the DeepL client, and many return a Result type (enum) that either resolves to a value of the type we expect, or one of the above Errors. So for some type T, the return type of a function returning a result is Result<T, Error>. While in the examples we unwrap the Result to pull out a value, it's common to implement more robust error handling in production code.

Get languages

Getting available languages requires specifying LanguageType as either Source or Target and returns a Result whose success value is a Vec<LanguageInfo>.

All instances of LanguageInfo contain language and name attributes. Target languages contain a third field, supports_formality which is true or false.

```rust // snip--

let source_langs = dl.languages(LanguageType::Source).unwrap();

for lang in source_langs { let code = lang.language; let name = lang.name;

println!("{code} {name}");
// BG Bulgarian

} ```

Translate text options

Translating text allows setting a number of options through the TextOptions builder, only one of which is required, namely the target_lang for the translation.

The list of options for text translation is as follows:

• target_lang: The target Language (required)
• source_lang: The source Language
• split_sentences: Decide how to split sentences from the input text. Can be one of
  • SplitSentences::None Do not split sentences.
  • SplitSentences::Default Split on punctuation and newlines (default).
  • SplitSentences::NoNewLines Split on punctuation only.
• preserve_formatting: Whether the translator should preserve the original format of the text. (default false)
• formality: The desired formality in the target language. Not all target languages support formality. Options include:
  • Formality::Default
  • Formality::More
  • Formality::Less
  • Formality::PreferMore
  • Formality::PreferLess
• glossary_id: The glossary id String to use for translation

Tag handling

The following are translation options related to tag handling

• tag_handling: Enable handling tags in the input text. Can be one of:
  • TagHandling::Xml
  • TagHandling::Html
• outline_detection: Whether the translator should automatically detect the outline (default true)
• splitting_tags: A comma-separated list of tags that are used to split sentences, e.g. "head,title,body" String
• non_splitting_tags: A comma-separated list of tags which do not split sentences, String
• ignore_tags: A comma-separated list of tags not to translate, String

Below is a more complex translation where we want to specify a source language, ignore newlines in the input, preserve formatting, and set a desired formality. We'll also use a custom glossary, ensuring the given glossary matches both the source and target language of this translation.

The function translate expects two arguments: a TextOptions object, and a Vec<String> containing one or more texts to be translated. It returns a Result whose Ok value is a TranslateTextResult with a single field, translations that holds a Vec<Translation>.

```rust // snip--

// Translate 'you are nice' to French // where the text contains a '\n' let text = vec![ "you\nare nice".to_string(), ];

let glossary = String::from("abc-123"); // your glossary id

let opt = TextOptions::new(Language::FR) // note new expects the required target lang .sourcelang(Language::EN) .splitsentences(SplitSentences::NoNewlines) .preserveformatting(true) .formality(Formality::PreferLess) .glossaryid(glossary);

let result = dl.translate(opt, text).unwrap();

let translation = &result.translations[0]; println!("{}", translation.text); // tu es gentille ```

A Translation has two attributes: text containing the translated text string, and detected_source_language, a string containing the language code of the source language detected by the server.

Here's an example where the input contains xml and where we only want to translate content inside the <p> tags.

```rust // snip--

let xml = r"

The red crab

Do you speak French?

let text = vec![xml]; let split = "p".tostring(); // split on

tags let ignore = "title".tostring(); // ignore