XLIFF Translate Plug-in
DITA-OT Translate Plug-in is a plug-in to create, auto-translate and re-merge XLIFF files, generating translated documentation in a targeted foreign language. It can create and consume files using either XLIFF 1.2 or XLIFF 2.1 format.
Example
This plug-in consists of three DITA-OT transforms:
-
The xliff-create transform creates XLIFF and skeleton files
from the
*.dita
files. -
The xliff-translate transform populates the
<target>
texts using an automatic translation service. - The xliff-dita transform recreates the DITA project using the translated texts.
Install
This is a standalone plug-in without dependencies which can be installed from the command line.
If the xliff-translate transform is to be used, the chosen translation service (usually an external cloud service) will need to be configured before use.
Run the plug-in installation commands:
dita install https://github.com/jason-fox/fox.jason.translate.xliff/archive/master.zip
The dita command line tool requires no additional configuration.
Automatic Translation Services
Several publicly available automatic translation cloud services are available for use, they typically offer a try-before-you-buy option and generally offer sample access to the service for without cost. Upgrading to a paid version will be necessary when transforming larger documents.
IBM Cloud Services
The IBM Language Translator allows you to translate text programmatically from one language into another language.
Introduction: Getting Started
Create an instance of the service:
- Go to the Language Translator External link icon page in the IBM Cloud Catalog.
- Sign up for a free IBM Cloud account or log in.
- Click Create.
Copy the credentials to authenticate to your service instance:
- From the IBM Cloud dashboard External link icon, click on your Language Translator service instance to go to the Language Translator service dashboard page.
- On the Manage page, click Show to view your credentials.
-
Copy the
API Key
andURL
values. -
Within the plug-in alter the file
cfg/configuration.properties
to hold yourAPI Key
andURL
.
By default the Frankfurt translation service URL used is:
https://gateway-fra.watsonplatform.net/language-translator/api/v3/translate
,
amend this when using a regional instance.
Microsoft Azure
Microsoft Translator provides multi-language support for translation, transliteration, language detection, and dictionaries.
Introduction: Overview
Create an instance of the service:
- Go to Try Cognitive Services
- Select the Translator Text APIs tab.
- Under Translator Text, select the Get API Key button.
- Agree to the terms and select your locale from the drop-down menu.
- Sign in by using your Microsoft, Facebook, LinkedIn, or GitHub account.
You can sign up for a free Microsoft account at the Microsoft account portal. To get started, click Sign in with Microsoft and then, when asked to sign in, click Create one. Follow the steps to create and verify your new Microsoft account.
After you sign in to Try Cognitive Services, your free trial begins. The displayed webpage lists all the Azure Cognitive Services services for which you currently have trial subscriptions. Two subscription keys are listed beside Speech Services. You can use either key in your applications.
Copy the credentials to authenticate to your service instance:
-
Copy each of the
API Key
andEndpoint
values. -
Within the plug-in alter the file
cfg/configuration.properties
to hold yourAPI Key
andURL
.
By default the global translation service URL used is:
https://api.cognitive.microsofttranslator.com/translate
, amend
this when using a regional instance.
Yandex Translate
The API provides access to the Yandex online machine translation service. It supports more than 90 languages and can translate separate words or complete texts.
Introduction: Overview
To sign-up to the service:
- Review the user agreement and rules for formatting translation results.
- Get a free API key.
- Read the documentation, where you will find instructions on enabling the API and detailed descriptions of its features.
After you sign in to your account select API Keys and create a new key as necessary. The latest endpoint can be found in the documentation.
https://translate.yandex.net/api/v1.5/tr/translate
Copy the credentials to authenticate to your service instance:
-
Copy each of the
API Key
andEndpoint
values. -
Within the plug-in alter the file
cfg/configuration.properties
to hold yourAPI Key
andURL
.
DeepL API
The DeepL API is accessible with a DeepL Pro subscription (DeepL API plan) only. The API is an interface that allows other computer programs to send texts to the DeepL servers and receive high-quality translations.
Introduction: Overview
To sign-up to the service:
- Open a DeepL APIdevelopers account. Note that not all accounts offer access to the DeepL API. It is essential that the account type includes REST API access.
- Fill out the application details and add a credit card. No payments are required for the first 30 days. You can cancel the card and still maintain free access for the trial period.
- Read the documentation, where you will find instructions on enabling the API and detailed descriptions of its features.
After you sign in to your account select API Keys and create a new key as necessary. The latest endpoint can be found in the documentation
https://api.deepl.com/v2/translate
Copy the credentials to authenticate to your service instance:
-
Copy each of the
API Key
andEndpoint
values. -
Within the plug-in alter the file
cfg/configuration.properties
to hold yourAPI Key
andURL
.
Usage
XLIFF 1.2 Invocation from the command line
1. to create an XLIFF 1.2 File and associated skeletons with run:
dita --format xliff-create \
--input document.ditamap \
--output out \
--xliff.version=1
A translate.xlf
file will appear in the out
directory along with a series of skeleton files.
<target>
elements.
2. to populate an existing XLIFF 1.2 File with auto-translated text:
dita --format xliff-translate \
--input translate.xlf \
--translate.service=[bing|deepl|watson|yandex] \
--translate.apikey=<api-key>
--xliff.version=1
The XLIFF 1.2 File is auto-translated in place, with translated text as shown:
<trans-unit>
elements which are @approved="no"
will be auto-translated.
XLIFF 2.1 Invocation from the command line
3. to create an XLIFF 2.1 File and associated skeletons with run:
dita --format xliff-create \
--input document.ditamap \
--output out \
--xliff.version=2
A translate.xlf
file will appear in the out
directory along with a series of skeleton files.
4. to populate an existing XLIFF 2.1 File with auto-translated text:
dita --format xliff-translate \
--input translate.xlf --translate.service=[bing|deepl|watson|yandex] \
--translate.apikey=<api-key> \
--xliff.version=2
The XLIFF 2.1 File is auto-translated in place, with translated text as shown:
<segment>
elements which are @state="final"
will not be re-translated.
Populating Skeletons from the command line
5. recreate *.dita
files using an XLIFF File and its associated
skeletons with run:
dita --format xliff-dita \
--input translate.xlf \
--output out \
--xliff.version=1|2
The translated *.dita
files are generated into the
out
directory.
<trans-unit>
should be marked @approved="yes"
when the <target>
element has been verified. Similarly
for XLIFF 2.1 each <segment>
should be marked as @state="final"
.
Parameter Reference
-
translate.from - Source language to use. Defaults to the
value in
configuration.properties
-
translate.to - Target language. Defaults to the value in
configuration.properties
-
translate.cachefile - Specifies the location of a
previously translated XLIFF file to be used. If the
@id
matches to a previously translated text snippet in the cache file, the text will be copied over and the snippet marked asapproved
. -
translate.service - Decides which translation service to use:
- bing - Connects to the Microsoft Azure Translation service
- custom - Sends the translate to an arbitrary URL using POST - use this to connect to proxies for Google Cloud Translate
- deepl - Connects to the DeepL API Translation service
- dummy - Avoids accessing a translation service, copies sources to target language directly without amendment.
- watson - Connects to the IBM Cloud Translation service
- yandex - Connects to the Yandex Translation service
-
translate.authentication.url - URL for creating an OAuth
token if needed for a service. Defaults to the value in
configuration.properties
. -
translate.apikey - API Key for the Translation service.
Defaults to the value in
configuration.properties
-
translate.url - URL for a Translation service. Defaults to
the value in
configuration.properties
-
xliff.version - Decides which XLIFF format to use.
Defaults to the value in
configuration.properties
:- 1 - XLIFF 1.2 format
- 2 - XLIFF 2.1 format