DeeplPlugin

Deepl translation service for Foswiki

Description

This plugin integrates Deepl into Foswiki as a translation system. That means, Deepl's API can be used to translate a text or even a whole topic. To use the service, you will need an API key and store it in your Foswikis configuration.

Create a user account at https://www.deepl.com/de/signup/. Then copy & paste the authentication key of your account into the $Foswiki::cfg{DeeplPlugin}{APIKey} .

Usage

Translations may either be used directly using the DeeplTranslate interface. In addition translations can be performed using the %DEEPL macro.

Use this to translate "Hello World" into the the user's language:

%DEEPL{"Hello World"}%

You may explicitly specify a source and target language as in:

%DEEPL{"Warte nicht, steig in das Rauschen der Sterne!" 
  source_lang="de" 
  target_lang="en"
}%

A larger section of text can be surrounded by %STARTDEEPL and %ENDDEEPL macros as in:

%STARTDEEPL{source_lang="de" target_lang="en"}%
---++ Vorwort
Die ISO (Internationale Organisation für Normung ) ist die weltweite Vereinigung nationaler
Normungsinstitute (ISO-Mitgliedskörperschaften). Die Erarbeitung internationaler Normen obliegt den
Technischen Komitees der ISO. Jede Mitgliedskörperschaft, die sich für ein Thema interessiert, für das ein
Technisches Komitee eingesetzt wurde, ist berechtigt, in diesem Komitee mitzuarbeiten. Internationale
(staatliche und nichtstaatliche) Organisationen, die mit der ISO in Verbindung stehen, sind an den Arbeiten
ebenfalls beteiligt. Die ISO arbeitet bei allen Angelegenheiten der elektrotechnischen Normung eng mit der
Internationalen Elektrotechnischen Kommission (IEC) zusammen.
%ENDDEEPL%

All available languages can be listed using the %DEEPL_LANGUAGES macro:

%DEEPL_LANGUAGES{
   format="   1 $langname ($langtag)"
   separator="$n"
}%

Parameters

The %DEEPL and %STARTDEEPL macros can be parametrized using:

• source_lang
• target_lang
• context
• split_sentences
• preserve_formatting
• formality
• glossary_id
• tag_handling
• outline_detection
• non_splitting_tags
• splitting_tags
• ignore_tags

See https://www.deepl.com/de/docs-api/translate-text/translate-text for an explanation.

Inplace translations

Your html text may have a lang attribute. This will automatically add a "Translate" button underneath to make the above text translatable. Example:

<div lang="en">
  From today until Saturday we are at the GET Nord in Hamburg. The fair is the
  industry meeting point of the north and the trade fair for electrical, sanitary
  and heating air conditioning.
</div>

%JQREQUIRE{"deepl"}% 

JavaScript API

To integrate translations into your user interface you may also use the Deepl jQuery module.

*Label:*
<input type="text" class="foswikiTextField" size="100" name="TopicTitle" id="test5" value="this is a test" />
<a href="#" class="jqDeepl" data-source="#test5" data-source-lang="en" data-target-lang="de">Translate</a>

*Textarea:*
<textarea class="foswikiTextArea" rows="10" cols="100" id="testarea5">
This is a test
</textarea>
<a href="#" class="jqDeepl" data-source="#testarea5" data-source-lang="en" data-target-lang="de">Translate</a>
%JQREQUIRE{"deepl"}%

When clicking on a jqDeepl link will translate a input or textarea be translated according to the parameters stored in HTML5 data attributes.

The Deepl jQuery module will export two functions:

• $(<selector>).deepl(<opts>): adds a translation controller to the given element
• $(<selector>).deelpTranslatable(<opts>): adds an in-place user interface to translate a text fragment

Installation Instructions

You do not need to install anything in the browser to use this extension. The following instructions are for the administrator who installs the extension on the server.

Open configure, and open the "Extensions" section. "Extensions Operation and Maintenance" Tab -> "Install, Update or Remove extensions" Tab. Click the "Search for Extensions" button. Enter part of the extension name or description and press search. Select the desired extension(s) and click install. If an extension is already installed, it will not show up in the search results.

You can also install from the shell by running the extension installer as the web server user: (Be sure to run as the webserver user, not as root!)

cd /path/to/foswiki
perl tools/extension_installer <NameOfExtension> install

If you have any problems, or if the extension isn't available in configure, then you can still install manually from the command-line. See https://foswiki.org/Support/ManuallyInstallingExtensions for more help.

Dependencies

Name	Version	Description
Foswiki::Plugins::MultiLingualPlugin	>=4.00	Required
Foswiki::Contrib::CacheContrib	>=3.00	Required

Change History

02 May 2024	normalize locales and language tags
29 Apr 2024	better detection of user vs browser vs document language when offering in-place translations
31 Jan 2024	initial release