In this post, I showed you how you can use Microsoft Dynamics Lifecycle Services to translate your AL project into a variety of languages.
As with most things, there are multiple ways to go about doing things. This post will look at the Microsoft Multilingual App Toolkit. This toolkit is integrated into Visual Studio but there is also a standalone version, called the Multilingual App Toolkit Editor.
With this tool you can manually do your translation and/or you can connect it to the Microsoft Translator service via Azure, which is what I will describe in this post.
Download and install the Multilingual App Toolkit Editor.
If all you want to do is work offline and manually do your translations, you can stop here. Continue on if you want to connect to the translation service in Azure, but note that you do need an active Azure subscription for this.
Enable the Translator Text API in Azure.
Using the Azure portal, do the following to add the Translator Text API to your Azure subscription:
- Choose “Create a Resource“.
- Search for “Translator Text API” and select it.
- On the Translator Text API blade, press the Create button to begin configuring the subscription.
- Fill in the fields accordingly for the API by giving it a name, pricing tier, etc. Note that there is a free tier option that lets you translate up to 2 million characters per month. Additional pricing info can be found here.
- Press the Create button to deploy the API to your Azure subscription. This might take a few minutes.
Get your Translator Text API authentication key.
Once the API has been deployed, you need to get your subscription key so that the Multilingual Tool can authenticate and connect to it.
- In the Azure portal, select “All Resources” and select the Azure subscription that you deployed the API to.
- In the list of resources, click on the Translator Text API service that you deployed.
- In the Translator Text API blade, select Keys.
- Copy one of the 2 keys that are associated with the service. You will need this key value in the next step.
Add Multilingual App Toolkit Editor credentials.
Now that we have the Translator Text API up and running, and the Multilingual App Toolkit Editor installed, we need to configure the authentication. We do that using the Windows Credential Manager.
- On your Windows machine, launch Credential Manager.
- Select Windows Credentials.
- Select Add a generic credential.
- Enter the following values:
- Internet or network address: Multilingual/MicrosoftTranslator
- User name: Multilingual App Toolkit
- Password: <the Translator Text API key that you retrieved earlier>
- Click OK.
- Close Credential Manager.
Ok, now that we have everything installed, deployed, and configured, we can open up the Multilingual App Toolkit Editor (search Multilingual Editor in your Start menu) and translate the XLF file from our AL project. You can learn about generating this file here.
- Copy the auto-generated ‘.g.xlf‘ file to create a new file in the same folder. Rename the file based on the AL standards here.
- Edit the new file and update the ‘target-language‘ property to be the language that you are translating the file to (e.g. fr-CA).
- Close and save the file.
- Using the Multilingual App Toolkit Editor, select Open and select your new file.
- From the ribbon, select Translate > Translate All. The toolkit will now use the Translator Text API in Azure to translate the file based on the source and target languages. This might take a few minutes based on the numbers of items that need to be translated in your solution.
- Once the translation is done you can manually review and edit any if you wish.
- Close and save the file.
Now you have your new translation file. Simply repeat the steps to generate each translation that your AL solution requires!
Submitting to AppSource
If you are submitting your solution to AppSource, even if you do not need multi-language support in your solution, you still must provide (at a minimum) a translation file for the base language (e.g. en-US) in which your solution is published.
Note that the auto-generated ‘.g.xlf’ file is NOT a properly formatted translation file and your solution will not pass validation if you do not create at least the base language file.
In the pic below you have the raw ‘.g.xlf’ file as it gets created during the AL project build process. As you can see, there is only a ‘source‘ property for the message control even though the ‘target-language‘ of the file is set to ‘en-US’:
In a properly formatted translation file, you will have both the ‘source‘ and the ‘target‘ properties:
In addition to the formatting, you can’t rely on editing the ‘.g.xlf’ file because it gets overwritten each time you build your AL project.
In short, use the ‘.g.xlf’ file ONLY as the source for generating other translation files.
EDIT: I was just informed that fellow MVP Tobias Fenster‘s ALRunner VS Code extension can (among many things) convert the ‘.g.xlf’ translation file into a properly formatted file. Quick and easy! Check it out here!