DeepL Application
 | Tools to translate content in XWiki using DeepL |
| Type | XAR |
| Category | Application |
| Developed by | |
| Active Installs | 0 |
| Rating | |
| License | GNU Lesser General Public License 2.1 |
Table of contents
Description
The DeepL application provides a couple of tools to help translate wiki content to DeepL.
Configuration
With the extension installed, you will first need to add the following keys to xwiki.properties in order to set your API key and the DeepL API domain to use :
deepl.api.domain=YOUR_DOMAIN
The value of deepl.api.domain can be either https://api-free.deepl.com or https://api.deepl.com depending if you are using the free tier of DeepL or if you have a paying subscription.
Once these parameters are set, restart the wiki for them to go into effect. After XWiki has restarted, you can verify that the integration is working by going to the page DeepL.Code.DeepLUsage, which will show the number of characters that you have used for DeepL translations.
DeepL Translation Macro
This application provides a macro which will display a link to some page content to the browser language through DeepL.
The macro ID is deeplTranslation. Once the extension is installed, head to DeepL.Code.DeepLTranslationMacro for a usage example.
| Parameter | Mandatory | Description | Default value |
|---|---|---|---|
| cssSelector | Yes | Indicate which CSS block should be translated. | N/A |
| classSelector | No | Allows to only display the translation link if the current page has at least one object of the class specified in classSelector. If the parameter is empty, no restriction gets applied. | N/A |
| extraCssClasses | No | Additional CSS classes to be added to the translation link. | N/A |
Translating comments
The application will expose a configuration in the wiki administration, in the section "Content" > "DeepL", allowing to enable or disable the display of translation links on comments in documents. By default, this feature is disabled.
Note that as XWiki does not store the language of each comment, we cannot determine if a comment is written in the same language as the page in which it stands, thus, this feature will add translation links under each comment, regardless of its language.
Javascript API
The application also provides a Javascript API to dynamically add new translation links in pages. This API can be reached through RequireJS and is defined in DeepL.Code.DeepLTranslationJSX. Below is an example of code used to add translation links to comments, used in DeepL.Code.DeepLCommentTranslation :
paths: {
'deepl-translation': "${escapetool.javascript($xwiki.getURL('DeepL.Code.DeepLTranslationJSX', 'jsx', "language=$!{xcontext.language}"))}"
}
});
require(['jquery', 'deepl-translation'], function($, api) {
if (api.needTranslation()) {
(XWiki && XWiki.domIsLoaded && loadComments()) || document.observe("xwiki:docextra:loaded", function(event) {
if (event["id"] = "Comments") {
loadComments();
}
});
}
function loadComments() {
$('.xwikicomment').each(function(index, value) {
let elem = $(value);
let link = api.createTranslationLink('#' + elem.attr('id') + ' .commentcontent');
elem.append(link);
api.registerTranslationLink(link);
});
}
});
Prerequisites & Installation Instructions
We recommend using the Extension Manager to install this extension (Make sure that the text "Installable with the Extension Manager" is displayed at the top right location on this page to know if this extension can be installed with the Extension Manager). Note that installing Extensions when being offline is currently not supported and you'd need to use some complex manual method.
You can also use the following manual method, which is useful if this extension cannot be installed with the Extension Manager or if you're using an old version of XWiki that doesn't have the Extension Manager:
- Log in the wiki with a user having Administration rights
- Go to the Administration page and select the Import category
- Follow the on-screen instructions to upload the downloaded XAR
- Click on the uploaded XAR and follow the instructions
- You'll also need to install all dependent Extensions that are not already installed in your wiki
