Lingua::Translation::DeepL

In brief

This blog posts proclaims and describes the Raku package “Lingua::Translation::DeepL” which provides access to the language translation service DeepL DeepL, [DL1]. For more details of the DeepL’s API usage see the documentation, [DL2].

Remark: To use the DeepL API one has to register and obtain authorization key.

Remark: This Raku package is much “less ambitious” than the official Python package, [DLp1], developed by DeepL’s team. Gradually, over time, I expect to add features to the Raku package that correspond to features of [DLp1].

---

Installation

Package installations from both sources use zef installer (which should be bundled with the “standard” Rakudo installation file.)

To install the package from Zef ecosystem use the shell command:

zef install Lingua::Translation::DeepL

To install the package from the GitHub repository use the shell command:

zef install https://github.com/antononcube/Raku-Lingua-Translation-DeepL.git

---

Usage examples

Remark: When the authorization key, auth-key, is specified to be Whatever then deepl-translation attempts to use the env variable DEEPL_AUTH_KEY.

Basic translation

Here is a simple call (automatic language detection by DeepL and translation to English):

use Lingua::Translation::DeepL;
say deepl-translation('Колко групи могат да се намерят в този облак от точки.');

# [{detected_source_language => BG, text => How many groups can be found in this point cloud.}]

Multiple texts

Here we translate from Bulgarian, Russian, and Portuguese to English:

my @texts = ['Препоръчай двеста неща от рекомендационната система smrGoods.',
              'Сделать классификатор с логистической регрессии',
              'Fazer um classificador florestal aleatório com 200 árvores'];
my @res = |deepl-translation(@texts,
        from-lang => Whatever,
        to-lang => 'English',
        auth-key => Whatever);
        
use Data::Reshapers;
#.say for @res;
to-pretty-table(@res, align=>'l', field-names=><text detected_source_language>)

# +-----------------------------------------------------------------------+--------------------------+
# | text                                                                  | detected_source_language |
# +-----------------------------------------------------------------------+--------------------------+
# | Recommend two hundred things from the smrGoods recommendation system. | BG                       |
# | Make a classifier with logistic regression                            | RU                       |
# | Make a random forest classifier with 200 trees                        | PT                       |
# +-----------------------------------------------------------------------+--------------------------+

Remark: DeepL allows up to 50 texts to be translated in one API call. Hence, if the first argument is an array with more than 50 elements, then it is partitioned into up-to-50-elements chunks and those are given to deepl-translation.

Formality of the translations

The argument “formality” controls whether translations should lean toward informal or formal language. This option is only available for some target languages; see [DLp1] for details.

say deepl-translation('How are you?', to-lang => 'German', auth-key => Whatever, formality => 'more');
say deepl-translation('How are you?', to-lang => 'German', auth-key => Whatever, formality => 'less');

# [{detected_source_language => EN, text => Wie geht es Ihnen?}]
# [{detected_source_language => EN, text => Wie geht es dir?}]

say deepl-translation('How are you?', to-lang => 'Russian', auth-key => Whatever, formality => 'more');
say deepl-translation('How are you?', to-lang => 'Russian', auth-key => Whatever, formality => 'less');  

# [{detected_source_language => EN, text => Как Вы?}]
# [{detected_source_language => EN, text => Как ты?}]

Languages

The function deepl-translation verifies that the argument languages given to it are valid DeepL from- and to-languages. See the section “Request Translation”.

Here we get the mappings of abbreviations to source language names:

deepl-source-languages()

# {bulgarian => BG, chinese => ZH, czech => CS, danish => DA, dutch => NL, english => EN, estonian => ET, finnish => FI, french => FR, german => DE, greek => EL, hungarian => HU, indonesian => ID, italian => IT, japanese => JA, latvian => LV, lithuanian => LT, polish => PL, portuguese => PT, romanian => RO, russian => RU, slovak => SK, slovenian => SL, spanish => ES, swedish => SV, turkish => TR, ukrainian => UK}

Here we get the mappings of abbreviations to target language names:

deepl-target-languages()

# {bulgarian => BG, chinese simplified => ZH, czech => CS, danish => DA, dutch => NL, english => EN, english american => EN-US, english british => EN-GB, estonian => ET, finnish => FI, french => FR, german => DE, greek => EL, hungarian => HU, indonesian => ID, italian => IT, japanese => JA, latvian => LV, lithuanian => LT, polish => PL, portuguese => PT, portuguese brazilian => PT-BR, portuguese non-brazilian => PT-PT, romanian => RO, russian => RU, slovak => SK, slovenian => SL, spanish => ES, swedish => SV, turkish => TR, ukrainian => UK}

---

Command Line Interface

The package provides a Command Line Interface (CLI) script:

deepl-translation --help

# Usage:
#   deepl-translation <text> [-f|--from-lang=<Str>] [-t|--to-lang=<Str>] [-a|--auth-key=<Str>] [--formality=<Str>] [--timeout[=UInt]] [--format=<Str>] -- Text translation using the DeepL API.
#   
#     <text>                  Text to be translated.
#     -f|--from-lang=<Str>    Source language. [default: 'Whatever']
#     -t|--to-lang=<Str>      Target language. [default: 'English']
#     -a|--auth-key=<Str>     Authorization key (to use DeepL API.) [default: 'Whatever']
#     --formality=<Str>       Language formality in the translated text. [default: 'Whatever']
#     --timeout[=UInt]        Timeout. [default: 10]
#     --format=<Str>          Format of the result; one of "json" or "hash". [default: 'json']

Remark: When the authorization key argument “auth-key” is specified set to “Whatever” then deepl-translation attempts to use the env variable DEEPL_AUTH_KEY.

---

Mermaid diagram

The following flowchart corresponds to the steps in the package function deepl-translation:

---

References

[DL1] DeepL, DeepL Translator.

[DL2] DeepL, DeepL API.

[DLp1] DeepL, DeepL Python Library, (2021), GitHub/DeepLcom.

Advertisement