deeperl
An Erlang/OTP client application for the official DeepL API Version 2.
Installation
Rebar3
{deps, [
% Latest release (git):
{deeperl, {git, "https://codeberg.org/l-x/deeperl.git", {branch, "main"}}},
% Specific version (git):
{deeperl, {git, "https://codeberg.org/l-x/deeperl.git", {tag, "0.10.0"}}},
% Latest version (hex):
deeperl,
% Specific version (hex):
{deeperl, "0.10.0"}
]}.
erlang.mk
See https://erlang.mk/guide/deps.html
Usage
Starting deeperl
deeperl is an Erlang/OTP application. Before using any of the functions you will have to start it.
To start in the console run:
$ rebar3 shell
Or simply add deeperl to the applications property of your .app files.
Authentication
To use the DeepL API an authentication key is required.
When booting deeperl this key is retrieved from application:get_env(deeperl, auth_key)
and stored in the deeperl server processes internal state.
yourapp.config
[
{deeperl, [
{auth_key, "your DeepL auth_key here"}
]}
].
The authorization key can also be set at runtime by calling
1> application:auth_key("your DeepL auth_key here").
ok
However, this does not change the corresponding application environment setting.
Note: deeperl determines what API endpoint to use based on the provided auth_key.
Configuring the http client
deeperl uses the builtin HTTP client to perform all HTTP requests.
By default deeperl uses the default
profile for httpc
. The used profile is stored in the application environment under the key httpc_profile
:
yourapp.config
[
{deeperl, [
{httpc_profile, my_profile}
]}
].
The httpc profile can also be set at runtime by calling
3> {ok, Pid} = inets:start(httpc, [{profile,my_profile}]).
{ok,<0.94.0>}
4> ok = deeperl:httpc_profile(Pid).
ok
Translating Text
5> {ok, Translations} = deeperl:translate("de", ["Rien ne vas plus", <<"Game over">>]).
{ok,[{"FR",<<"Nichts läuft richtig"/utf8>>},
{"EN",<<"Spiel vorbei">>}]}
6> {ok, Translations} = deeperl:translate("de", ["<b>Rien</b> ne vas plus", <<"Game over">>], #{tag_handling=>xml, formality=>less}).
{ok,[{"FR",<<"<b>Nichts</b> läuft richtig"/utf8>>},
{"EN",<<"Spiel vorbei">>}]}
Listing supported languages
Supported source languages
7> {ok, SourceLanguages} = deeperl:source_languages().
{ok,[{"BG","Bulgarian"},
{"CS","Czech"},
{"DA","Danish"},
{"DE","German"},
...
8> {Language, Name} = hd(SourceLanguages).
{"BG","Bulgarian"}
Supported target languages
9> {ok, TargetLanguages} = deeperl:target_languages().
{ok,[{"BG","Bulgarian",false},
{"CS","Czech",false},
{"DA","Danish",false},
{"DE","German",true},
...
10> {Language, Name, SupportsFormality} = hd(TargetLanguages).
{"BG","Bulgarian",false}
Monitoring usage
11> {ok, {CharacterCount, CharacterLimit}} = deeperl:usage().
{ok,{28788,50000000}}
Managing glossaries
List language pairs supported by glossaries
12> {ok, LanguagePairs} = deeperl:glossary_language_pairs().
{ok,[{"de","en"},
{"en","de"},
{"en","es"},
{"en","fr"},
{"es","en"},
{"fr","en"}]}
Creating a glossary
13> Entries = [{<<"Entry1">>, <<"Translation1">>}, {<<"Entry2">>, <<"Translation2">>}, {<<"Entry3">>, <<"Translation3">>}].
[{<<"Entry1">>,<<"Translation1">>},
{<<"Entry2">>,<<"Translation2">>},
{<<"Entry3">>,<<"Translation3">>}]
14> {ok, Glossary} = deeperl:glossary_create(<<"Glossary Name">>, "en", "de", Entries).
{ok,#{creation_time => "2021-09-29T07:31:01.19704+00:00",
entry_count => 3,
id => "610a3145-be30-424c-8eeb-bb06a405c90e",
name => <<"Glossary Name">>,source_lang => "en",
target_lang => "de"}}
15> GlossaryId = maps:get(id, Glossary).
"610a3145-be30-424c-8eeb-bb06a405c90e"
Listing glossary information
16> {ok, Glossary} = deeperl:glossary_information(GlossaryId).
{ok,#{creation_time => "2021-09-29T07:31:01.19704+00:00",
entry_count => 3,
id => "610a3145-be30-424c-8eeb-bb06a405c90e",
name => <<"Glossary Name">>,source_lang => "en",
target_lang => "de"}}
Listing entries of a glossary
17> {ok, _} = deeperl:glossary_entries(GlossaryId).
{ok,[{"Entry1","Translation1"},
{"Entry2","Translation2"},
{"Entry3","Translation3"}]}
Listing glossaries
18> {ok, Glossaries} = deeperl:glossary_list().
{ok,[#{creation_time => "2021-09-29T07:31:01.19704+00:00",
entry_count => 3,
id => "610a3145-be30-424c-8eeb-bb06a405c90e",
name => <<"Glossary Name">>,source_lang => "en",
target_lang => "de"},
#{creation_time => "2021-09-28T14:06:47.881791+00:00",
entry_count => 1,
id => "66a9557a-9092-4efc-901a-650a82c644ba",
name => <<"Test3">>,source_lang => "en",target_lang => "de"},
...
Deleting a glossary
19> ok = deeperl:glossary_delete(GlossaryId).
ok