How to use the Multilingual App Toolkit
[ This article is for Windows 8.x and Windows Phone 8.x developers writing Windows Runtime apps. If you’re developing for Windows 10, see the latest documentation ]
The Multilingual App Toolkit integrates with Microsoft Visual Studio to provide Windows Store apps and Windows Phone apps with translation support, translation file management, and editor tools.
The toolkit:
- Helps you manage resource changes and translation status during development.
- Provides a UI for choosing languages based on configured translation providers.
- Supports the localization industry-standard XLIFF file format.
- Provides a pseudo-language engine to help identify translation issues during development.
- Connects with the Microsoft Language Portal to easily access translated strings and terminology.
- Connects with the Microsoft Translator for quick translation suggestions.
Instructions
Step 1: Design for globalization and localization.
The Multilingual App Toolkit requires your app to be designed for globalization and localization. Once your app supports the Windows Store app or Windows Phone app globalization and localization design model, the toolkit makes adding additional languages quick and easy. Refer to Quickstart: Translating UI resources for more information about how to globalize Windows Store apps.
Step 2: Download the Multilingual App Toolkit.
Download and install the toolkit from Multilingual App Toolkit.
Step 3: Enable the Multilingual App Toolkit.
The Multilingual App Toolkit must be enabled for your project before you can begin to localize the app.
To enable the Multilingual App Toolkit:
- Open the project solution file.
- Select the desired project in the solution explorer.
- On the Tools menu, select Enable Multilingual App Toolkit.
The Multilingual App Toolkit is now ready to use as indicated by the message "Multilingual App Toolkit was successfully enabled on the selected project" in the Multilingual App Toolkit output window.
Note Pseudo (qps-ploc) translation is automatically added to your project. For details on how pseudo language can be used during testing, see the step below, "Test your app using Pseudo Language".
Step 4: Add languages to the project.
To add languages to your project:
- Right-click your project.
- Select Add translation languages.
- In the Translation Languages window, select the languages you want to release and click OK. The Multilingual App Toolkit output window confirms the addition of the selected languages.
- Right-click the project and choose Rebuild to populate contents of the .xlf files in the MultilingualResources language folder.
Windows Store apps
- The language files are placed in the MultilingualResources folder. Strings are populated into these files during the next build. After the initial build, additional languages are populated with the most recent known resource and are updated during the next build.
- Installed Translation Providers, such as the Microsoft Language Portal and Microsoft Translator services, can be used to translate your app's resources. When a provider supports a specific language, the provider's icon is displayed next to the language name.
- Once a language is added to the project it cannot be removed by un-checking the box in the Translation Languages window. To remove a language, right-click on the language-specific .xlf file and select Delete.
Windows Phone apps
- The language files are added to the same folder as the related resx file. Strings are initially populated into these files when created. Updates are applied during each build.
- Installed Translation Providers, such as the Microsoft Language Portal and Microsoft Translator services, can be used to translate your app's resources. When a provider supports a specific language, the provider's icon is displayed next to the language name.
- To remove languages later, right-click the language(s) in the related resx folder and select Delete.
Step 5: Test your app using Pseudo Language.
Pseudo Language is an artificial modification of the software product intended to simulate real language localization. The pseudo language can be used to detect potential localizability issues or bugs early in the project cycle, before the actual localization starts. For more details about localizability testing with Pseudo Language see Localizability Testing.
To generate pseudo-localized translations:
- Right-click AppName_qps_ploc.xlf in Solution Explorer.
- Select Generate pseudo translations.
Windows Store apps
Before you test a pseudo-localized Windows Store app, you must add Pseudo Language to your Windows 8 language preferences.
To add Pseudo Language to Windows 8:
- Open the Control Panel, and select Clock, Language, and Region > Language.
- Click Add a language.
- In the search box, type qps-ploc. Be sure to type the full language code; anything less will not return Pseudo Language in the search results.
- Select English (pseudo-qps) and click Add.
- Ensure that English (qps-ploc) is at the top of your preferred language list.
Windows Phone apps
Windows Phone does not provide the ability to set pseudo as the preferred language. Therefore you must add a small amount of code to enable the display of pseudo translations.
To enable pseudo, add the following code to the App.xaml.cs file in the InitializeLanguage() method, just after the try statement:
Thread.CurrentThread.CurrentCulture = new CultureInfo("qps-ploc"); Thread.CurrentThread.CurrentUICulture = new CultureInfo("qps-ploc");Note Be sure to comment out this code after you have completed your pseudo testing.
You can now start testing your pseudo-localized app.
Step 6: Translate your app into selected languages.
The Multilingual App Toolkit is incorporated within the build process. During each build, updated strings are automatically added to each language .xlf file.
After you've tested your app by using Pseudo Language, there are three options to translate your app into other languages for release.
Translate the app yourself.
If you have language skills in more than one language, use the included Multilingual Editor to translate strings individually.
- Right-click the .xlf file you want to translate.
- Click Open.... This will open an external editor.
- Select the row that contains the string you wish to translate.
- Type the translation into the Translation column.
Note If the Multilingual Editor does not open, select Open With… and set the Multilingual Editor as the default program to open.
Send the .xlf files to a third party for translation.
Send and receive .xlf files.
You may outsource the translation and editing work to localizers. You can send your files by e-mail or to a location on your hard drive from within the Multilingual App Toolkit.
To send your .xlf files to localizers:
Right-click your desired language .xlf files and select Send for translation.
Select File folder location when you want to send your .xlf files to a local folder.
-OR-
Select Mail recipient when you want to send your .xlf files by e-mail.
Optionally select Use compressed (zipped) folder to place the selected .xlf files into a .zip file.
Import translated .xlf files into your project.
After localizers complete translation work and you receive the translated .xlf files, you can import the translated .xlf files into your project and build the localized app.
To import translated .xlf files to your project:
- Right-click the desired language .xlf files.
- Select Import translation.
- Select the .xlf or .zip files to import.
Note The import process performs basic validation before importing. This ensures that the target culture information matches between the existing .xlf files and the .xlf files being imported.
Use the integrated translation services.
The translation services are integrated into the Visual Studio IDE as well as the Multilingual Editor. This provides easy access to translation services while developing your product as well as localizing your resources.
To access the translation services inside Visual Studio, right-click one or more .xlf files in your project and select Generate machine translation.
Using the Multilingual Editor provides the same translation support as well as adding interactive translation suggestions, which enable you to select the translation that best fits your resource strings. After the translation suggestion is provided, you are able to fine-tune the string for your translation style.
Two providers are shipped with the Multilingual App Toolkit:
- Microsoft Language Portal provider enables translation recycling and terminology matching support based on translations of the user interface text for Microsoft products and services.
- Microsoft Translator provider enables on-demand machine translation services.
You and your translator(s) can manage the status of translations in the Multilingual Editor to review uncertain translations later. You can set the status of each string in the Properties tab. Status values are: New, Needs review, Translated, Final, and Signed off. The indicator at the left of the row shows the status. When all rows show green in the Multilingual Editor, your translation work is done.
Step 7: Upload your app to the Store.
Before you start the Store Certification process, you must exclude the AppName_qps-PLOC.xlf file from your project. Pseudo Language is used to detect potential localizability issues or bugs, but it is not a valid Store language. If it is not removed, your app will fail during the Store Certification process.
Related topics
Multilingual App Toolkit FAQ & troubleshooting guide