The Deepl bridge plugin (WXM_DEEPL) offer a set of API (Services) to translate text using the Deepl API and an Web User Interface to manage client based glossaries and other options.

Web User Interface

There are two versions of web pages: 

• a user version, with standard security (user account login)

The menu is accessible via the URI /_plugins/WXM_DEEPL/page/home.jspz 

• and an "admin" version, with role-based security (tomcat admin account login).

The menu is accessible via the URI /_plugins/WXM_DEEPL/page/admin/home.jspz 

Glossaries feature

This page lists the glossaries stored on the DeepL server. In user mode, you only have access to the glossaries corresponding to the name configured for this server. In administration mode, certain roles can view all glossaries on all servers. 

This page also allows you to :

• delete a glossary

• view glossary information

• export glossary (in TSV format)

Upload functionality

This page lets you upload glossaries to the DeepL server. You can upload one or more TSV files, or a ZIP file containing TSV files.

The source and target languages are extracted from the file name, which must have the following format: 

prefix-source-target.tsv

• The prefix is optional (in this case the file will be source-target.tsv).

• Source is the source language in ISO format (without country)

• Target is the target language in ISO format (without country)

The upload page has two areas: 

• at the top, a drag-and-drop area for downloading (a button also opens a file selector)

• at the bottom, a results log, where the various glossaries created, alerts on rejected entries in these glossaries and errors are displayed

Translate feature

This page lets you translate texts directly, as in DeepL, with the additional options provided by the DeepL API.

Usage

This page shows 

• the type of account DeepL associated with the key used

• usage information provided by the DeepL API: 

  • the global number of characters translated by the DeepL account, 

  • the limit associated with the DeepL account

  • a Boolean indicating whether the limit has been reached

• the number of namespaces

• the total number of glossaries

• the number of glossaries per namespace

DeepL status

This is a direct link to the DeepL page, which indicates the status of the service.

Services / API

Services endpoints are available either

• with user access, subject to standard security

In general, the URI is /api/wedia/deepl/{serviceId}

• with admin access (tomcat), subject to role-based security

In general, the URI is /api/wedia/deepl/admin/{serviceId}

• with specific access

In the parameters, we call ISO locale, locales in the form of a language in ISO-639-1 alpha-2 with country in ISO 3166-1 alpha-2, with hyphen (-) or underscore (_) as separator are accepted.

API Documentation is available by one of these end points:

• ReDoc: /api/wedia/deepl/doc/redoc

• SwaggerUI: /api/wedia/deepl/doc/swaggerui

• OpenAPI: /api/wedia/deepl/doc

Reading glossary data

Service ID: read

Method: GET

Access:

• user (read security action)

• admin

Query parameter

• id: glossary identifier

Examples

User

Admin

Get the list of glossaries

Service ID: glossaries

Method: GET

Access:

• user (read security action)

• admin

Query parameter

• query (json) : filter

Examples

User

Admin

Create a glossary

Service ID: create

Method: POST

Access:

• admin

Parameters (multipart/formdata)

• source : ISO source language

• target: ISO target language

• entries: inputs

Example

Delete a glossary

Service ID: delete

Method: DELETE

Access:

• user (delete security action)

• admin

Query parameters

• id a glossary identifier (multiple values possible) 

Examples

Upload a glossary

Service ID: upload

Method: POST

Access:

• user (security action upload)

• admin

Parameters (multipart/formdata)

• file tsv or zip file containing tsv (multiple values possible), For TSV, the basename is

  • a trigram (separated by a hyphen)

    • prefix 

    • source language 

    • target language

  • a bigram (separated by a hyphen)

    • source language 

    • target language

• mode (optional)

  • text to get response as text/plain

  • other or no value to get response as application/json

Examples

User

Admin

Translating texts

Service ID: translate

Method: POST

Access:

• user (translate security action)

• admin

Parameters

• body (application/json)

Basically, the exact form of the Deepl API, with improvements:

• text to indicate the text(s) to be translated

  • deepl syntax: an array of strings

  • extended syntax: x, where x = string | array of x 

• target_lang to specify the target language

  • syntax DeepL : a string, among the following values:

    • BG - Bulgarian

    • CS - Czech

    • DA - Danish

    • DE - German

    • EL - Greek

    • EN - English (unspecified variant for backward compatibility; please select EN-GB or EN-US instead)

    • EN-GB - English (British)

    • EN-US - English (American)

    • ES - Spanish

    • ET - Estonian

    • FI - Finnish

    • FR - French

    • HU - Hungarian

    • ID - Indonesian

    • IT - Italian

    • JA - Japanese

    • KO - Korean

    • LT - Lithuanian

    • LV - Latvian

    • NB - Norwegian (Bokmål)

    • NL - Dutch

    • PL - Polish

    • PT - Portuguese (unspecified variant for backward compatibility; please select PT-BR or PT-PT instead)

    • PT-BR - Portuguese (Brazilian)

    • PT-PT - Portuguese (all Portuguese varieties excluding Brazilian Portuguese)

    • RO - Romanian

    • RU - Russian

    • SK - Slovak

    • SL - Slovenian

    • SV - Swedish

    • TR - Turkish

    • UK - Ukrainian

    • ZH - Chinese (simplified)

  • extended syntax: ISO locales are accepted and converted

• source_lang to specify the source language (optional: if not specified, DeepL will try to detect the language).

  • syntax DeepL : a string, among the following values:

    • BG - Bulgarian

    • CS - Czech

    • DA - Danish

    • DE - German

    • EL - Greek

    • EN - English

    • ES - Spanish

    • ET - Estonian

    • FI - Finnish

    • FR - French

    • HU - Hungarian

    • ID - Indonesian

    • IT - Italian

    • JA - Japanese

    • KO - Korean

    • LT - Lithuanian

    • LV - Latvian

    • NB - Norwegian (Bokmål)

    • NL - Dutch

    • PL - Polish

    • PT - Portuguese (all Portuguese varieties mixed)

    • RO - Romanian

    • RU - Russian

    • SK - Slovak

    • SL - Slovenian

    • SV - Swedish

    • TR - Turkish

    • UK - Ukrainian

    • ZH - Chinese

  • extended syntax: ISO-639-1 alpha-2 locales with ISO 3166-1 alpha-2 countries, with hyphen (-) or underscore (_) separator are accepted (and converted)

• context (optional), a string (no specific processing by the WXM_DEEPL API)

• split_sentences to divide a text into sentences

  • syntax DeepL : a string taking one of the following values

    • 0 no phase splitting

    • 1 (default when tag_handling is not html) punctuation and carriage return trimming 

    • nonewlines (default value when tag_handling is html) punctuation-based slicing only (without taking carriage returns into account)

  • extended syntax :

    • all equivalent to 1

    • off equivalent of 0

    • a boolean set to true

      • if tag_handling is html, is equivalent to nonewlines

      • otherwise equivalent to 1 (or all)

    • a false Boolean equivalent to 0 (or off)

• preserve_formatting to indicate whether the translation respects the original formatting

  • syntax DeepL: a Boolean

• formality to indicate whether the translated text should tend towards formal or informal language

  • syntax DeepL : one of the following values (string), optional :

    • default 

    • more for a more formal language 

    • less for a more informal language 

    • prefer_more for a more formal language if available, otherwise return to default formality

    • prefer_less for a more informal language if available, otherwise return to default formality

  • extended syntax: no case sensitivity and preferMore is equivalent to prefer_more and preferLess is equivalent to prefer_less.

• glossary_id to specify the glossary identifier to be used

  • syntax DeepL: a string

  • extended syntax: a Boolean

    • if true, and source_lang is specified, automatically selects the glossary associated with the source_lang - target_lang pair if it exists

• tag_handling to indicate how tags are handled

  • syntax DeepL : a string, optional among the following values

    • html

    • xml

  • extended syntax: no case sensitivity

• outline_detection to specify whether to use automatic XML structure detection (default on)

  • syntax DeepL: a Boolean, optional

• non_splitting_tags

  • syntax DeepL: an array of strings 

  • extended syntax: x, where x = string | array of x 

• splitting_tags

  • syntax DeepL: an array of strings 

  • extended syntax: x, where x = string | array of x 

• ignore_tags

  • syntax DeepL: an array of strings 

  • extended syntax: x, where x = string | array of x 

Response

This is a JSON, in the form of an object array. Each object has the following properties:

• text: the translated text

• detected_source_language : the detected language ( ISO-639-1 alpha-2 )

• target_language (does not exist in the DeepL response): the target language used. 

• glossary_id (does not exist in the DeepL response): the identifier of the glossary used.

Export a glossary (in TSV format)

Service ID: export

Method : GET

Access:

• user (read security action)

• admin

Query parameter

• id: glossary identifier

• filename: (optional) a prefix for the file name (which will be generated in the format expected for import). This parameter can also be used to obtain an extension other than tsv

If the parameter is missing, the filename format extension will be <source language>-<target language>.tsv

Examples

User

Admin

Obtaining usage

Service ID: usage

Method : GET

Access:

• only admin

Service status test

URL: /api/wedia/deepl/ping

Method : GET

Access: no authentication

Answer:

• 200 if service available and operational

• 404 if service unavailable

• 503 if DeepL PLC not operational

Analytics

Statistics graphs are integrated into the "New analytics" backoffice page.

Open

When a menu list is explicitly specified for a role in the WXL_ANALYTICS_V2 plugin configuration (available_menus parameter), the value translation must be added into the list to access it.

Description of event fields in the deepl_bridge_api index

Open

Plugin configuration

Namespaces for glossaries

Glossaries are organized by namespace: all servers/environments using the same name as a base share the same glossaries. By default, a server's namespace is the value of the "company name" variable. To configure the namespace, use the glossary_name configuration property of the WXM_DEEPL plugin. This is a variable string. You can specify a fixed name, for example, for a local server, if you don't want to share glossaries, or use variables as required (such as wanting to have different glossaries for integration, staging and production).

Key DeepL API

The DeepL API key that enables use of the DeepL translation service must be specified in the deepl_api_key property. It is possible to specify a local key, which will not be saved in the nar, for testing purposes in the deepl_api_key_local property. If specified, this key will be used.

2024.2 The Wedia DeepL API key is used if no value is specified for the parameter deepl_api_key.

Exchanges between InDesign robots and the DeepL API

InDesign plugin translation services use an end point served by the WXM_DEEPL plugin to use the DeepL translation API. 

The token_auth_key property is the encryption key for the tokens used by the InDesign plugin to use this end point. This key is mandatory, otherwise the end point is closed.

The token_auth_exp property is used to configure the time before expiry of a token: it is a number, for an amount in seconds, or a character string for an amount followed by the unit (ms for millisecond, s for second, m for minute, h for hour).

Configure API connection DeepL

The deepl_api_config property is used to specify a configuration for connection to the DeepL API. It is a JSON object with the following properties: 

• url a character string indicating the call URL (by default, this URL is automatically selected by the DeepL API according to the type of account (associated with the key used).

• proxy configuration, a JSON : 

  • type : proxy type ( DIRECT, HTTP or SOCKS )

  • port: the port

  • host: the host

• maxRetries the maximum number of trials before failure

• timeout the timeout ( a number, for an amount in seconds, or a character string for an amount followed by the unit (ms for millisecond, s for second, m for minute, h for hour)

Authorized roles

These are the roles authorized for various actions that can be carried out in administration mode (security for actions carried out by a user connected via surfing is provided by the usual security).

Translation

The translate_roles property is used to indicate the role(s) authorized to perform translation (either by the dedicated web page or by the dedicated end point). It is a string or a JSON array, in GSON Lenient format. These roles do not affect access to the translation service by InDesign robots.

internalDebugErrorLoggedAsWarn

Some error messages are only logged in debug mode, to avoid filling stacktrace logs. The internalDebugErrorLoggedAsWarn property is used to promote these error logs to warn level.

Temporary directory

The temp_dir_path property is used to specify the temporary folder. It is a variable string.

Billing hits

2024.2 If you use the Wedia DeepL API key, character counts will always be set to 0 by default (no translation billing if you use the Wedia account).

Setting the billing_hits_even_wedia_key parameter to true forces the character count to be carried forward if the Wedia key is used.

The no_billing_hits parameter is set to true to force the character count to be set to 0 regardless of the key used (thus cancelling billing per translated character).

Variables used in variable strings 

Variable strings are configuration properties in which variables can be specified, such as ${java.io.tmpdir}/_wedia_deepl_bridge_temp, which is the default value for the temp_dir_path property. A variable is indicated by its name between ${ and } and will be replaced by the value of the corresponding variable.

• app.site.name the site name

• app.company.name the name of the user company

• app.node.name the node name

• app.env.type the type of environment

• app.cluster.name the cluster name

• app.server.name the server name

• app.var.<variable name> for any variable that can be obtained by ApplicationVariables.getInstance().getVariableValue( "<variable name>" );

• app.san the result of Startup.getDirectoryRegistryFile().toString()

• data.san the result of Startup.getDirectorySanFile().toString();

• a system property name (configured by -D on the command line or standard Java)