Globalizing Strings in Microsoft .NET with the Multilingual App Toolkit

Throughout my career, I have learned that supporting different spoken languages and locales is crucial for applications and services in the global economy, regardless of what managers or project managers may initially say. Unfortunately, all the teams I joined did not properly code for this at the start of the project. This mistake proved to be very time-consuming and costly when we had to do it later in the project's lifetime. Therefore, I strongly advise that this task be done at the beginning and continuously throughout the project.

Fortunately, the .NET team has made it easy and seamless to globalize strings. In this article, I will demonstrate how to do this and introduce you to the Multilingual App Toolkit, which makes string translation fast and cost-effective. It was so simple that I only needed a few hours (including my learning curve) to convert the Spargine Dev Tool to Danish, Hindi, and Spanish.

Globalizing Strings

My first and foremost rule for globalizing strings is to put any string that a user might see into a resource file. I exclude logging or exception messages from this rule since those messages are for developers. There are several steps to globalizing strings to make them easily translatable to different languages and to enable the runtime to choose the correct resource.

When reviewing code, I have observed that most developers tend to use strings in their code in the following manner. The following examples are taken from the Spargine Dev Tool.

To globalize this string, simply put the string in a resource file. Using CodeRush, simply right click on the string and select Extract String to Resource. After choosing a name for the string resource, the code will look like this.

For a simple string like this, then that’s all you need. But there are different steps involved if dynamic values are injected into the string like in this example.

The code above uses string interpolation, but that does not work with resources. First, refactor the code to use String.Format() as shown in this example.

It’s very important to add CultureInfo.CurrentCulture in front of the string so that the runtime can process it correctly. Then refactor the string into a resource. Afterward, it should look like this:

That’s it. You are all done! The next step is to create different language resource files. Once that is done, for the culture the thread is running from, the runtime will automatically pick the correct resource file. Can’t get easier than that!

Translate Strings with the Multilingual App Toolkit

I have had experience globalizing many applications, and I know that translating everything can be a costly and time-consuming process if you use a third-party translation service. However, the Visual Studio team has made this task much easier and faster by releasing the Multilingual App Toolkit. You can find instructions on how to use the toolkit at this link: https://bit.ly/CSMLAT.

Next, I will demonstrate how I used the toolkit to translate the Spargine Dev Tool. Please note that some of the instructions provided with the toolkit are incorrect, and I will provide updated instructions.

Install Step 1: Create Translator Instance in Azure

Although it is not necessary, using the Translator in Azure can make translating strings very easy and fast. If you choose to use it, follow these steps:

1. If you haven't already done so, create a new Cognitive Services Translator instance in the Azure portal.
2. After the instance is deployed, go to its settings, and navigate to Keys and Endpoint.
3. Copy the value of Key 1, as we will need it later.

Install Step 2: Multilingual App Toolkit

In your browser, go to the Visual Studio Marketplace. There are two extensions available for the toolkit, one for Visual Studio 2017 – 2019 and one for Visual Studio 2022. Install the correct one for the version of Visual Studio you are using.

Install Step 3: Multilingual App Toolkit Editor

Next, you will need the Multilingual App Toolkit Editor. Not sure why it’s not installed with the toolkit, so you will need to navigate to this link and install the correct version that you want to use: https://bit.ly/CSMLATE.

Install Step 4: Enable the Multilingual App Toolkit for Your Project

Next, you need to enable the toolkit for your project. Go to Tools – Multilingual App Toolkit and select Enable selection. Doing this allows the toolkit to keep the resource files in sync during a build. You only need to do the first four steps once. 

Create a Resource for Each Language That Needs to Be Supported

The next step is to create a new resource file for each language that the application needs to support. To do this, follow these steps:

1. Right-click on the default resource file (in my project, this file is named Resources.resx) and select Multilingual App Toolkit - Add Translation Languages.
2. You will see a dialog box appear:

To create a new resource file for each language that the application needs to support, follow these steps:

1. In the Add Translation Languages dialog box, check each language that will be supported.
2. Click OK. This will create a new resource file for each language. For example, for the Spargine Dev Tool, I selected Spanish, and the resource file created is named Resources.es.resx.
3. A new xlf file will also be created in the MultilingualResources folder. For Spanish, the file created for the Spargine Global Tool is named dotNetTips.Spargine.Dev.Tool.es.xlf.

Using the Multilingual App Toolkit Editor

Once the different languages are configured, you can use the Multilingual App Toolkit Editor to quickly translate all the strings using the Translator service in Azure. To open the editor, follow these steps:

1. Right-click on the xlf file you want to translate and select Open With and then Multilingual App Toolkit Editor.
2. While you're there, it's helpful to set this app as the default app for opening xlf files.
3. You will now see the editor.
4. The first time you open the editor, it will ask you to set up the connection to the Azure Translator.

In Subscription Key, enter the Key 1 value from Install Step 1. Also, set it to the region the translator is running from.

If there are any resource strings that you do not want to translate, navigate to the source you want, and select No in the Translatable drop-down menu.

To translate the strings, you can either do it manually by changing the text in the Translation text box, or you can use the Azure Translator to do it for you. To use the translator, go to the Translate menu item and select Translate All. Depending on the number of resource strings, the Azure Translator will complete the translation in just a few seconds. After the translation is completed, click Save, and you're done! Repeat this step for each xlf file.

If you add a new string resource to the default resource file, run Build. Then go to each xlf file, run the editor again, and save before moving on to the next file. Run Build again, and everything will be synced up.

For as long as I have been globalizing apps in .NET, I have recommended putting all the resources in a resource-only class library. However, currently, the Multilingual App Toolkit does not work with a class library. I have submitted an issue on GitHub for the team.

Summary

The Multilingual App Toolkit Editor offers additional features by allowing you to tag translations as "Need Review," "Translated," or "Final." You can also export the xlf files to a zip file, which can be edited by a third-party service. After editing, the files can be imported to update the resources in the project.

I also write about globalization in Rock Your Code: Code & App Performance for Microsoft .NET and Rock Your Code: Coding Standards for Microsoft .NET. I hope you will pick up a copy from Amazon.com.

Please share any comments or questions below, I'd love to hear from you.