Multilingual App Toolkit FAQ & troubleshooting guide
[ 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 ]
Installation
What are the system requirements?
Supported Operating Systems: Windows 8 (RTM or greater, 32-bit or 64-bit editions).
Required Software: Microsoft Visual Studio.
Disk Space Requirements: 10MB (32-bit), 10MB (64-bit).
What programming languages are supported by the Toolkit?
The Toolkit supports all Windows app development that uses the Windows Runtime (WinRT) environment. This includes both .resw (XAML) and .resjson (JavaScript) files, but for the rest of this document we'll refer only to .resjson files.
Enabling the Multilingual App Toolkit
Do I need .resjson files in multiple languages?
No. One of the key benefits of the Toolkit is that .resjson files in multiple languages are not required. The Toolkit manages and synchronizes your app's resources by using the project's .xlf files. This removes the challenges associated with keeping content synchronized across multiple .resjson files.
Projects that contain matching .resjson and .xlf files cause the translations from the .xlf file to be ignored. When this happens, a warning is displayed during the build to let you know that the .xlf translations are not included in the final app. A .resjson file and .xlf file match when they have a target language with the same language code. An example of a matching pair would be strings\de-DE\resources.resjson and a German (Germany).xlf with target-language attributes of "de-DE".
Can I have .resjson files in multiple languages
Yes, but we don't recommend it. If you want to include .resjson files in multiple languages in your project and use the Toolkit, make sure you don't have matching .resjson and .xlf files.
I don't see an option in the Tools menu to Enable Multilingual App Toolkit.
Try these steps:
- Make sure you select the Project name, not the Solution, before selecting Tools.
- Verify that the Toolkit extension is installed by using the Extension Manager.
- Verify that your project is a Windows Store app project.
I do not see Multilingual App Toolkit build started. when I build my project.
Ensure that you have enabled your project by using Enable Multilingual App Toolkit from the Tools menu. If your app was enabled with a previous version, you must disable and then enable the Multilingual App Toolkit by using the Tools menu. This updates the project to work with the new version of the Toolkit.
Ensure that the "Build Task for all Visual Studio editions" component was installed. This build component is installed with the extension, but can be manually deselected during the installation. This component is required to update the .xlf files and add the translation into the PRI file. When this component is installed and working correctly, you will see the following build messages:
1> Multilingual App Toolkit build started.
1> Multilingual App Toolkit build completed successfully.
The Toolkit is reporting that it did not locate any XLIFF language files during the build.
Message:
No XLIFF language files were found. The app will not contain any localized resources.
This happens when the Toolkit does not find any files in the project with an extension of .xlf. These files are placed in the "MultilingualResources" folder by default. They can be moved, but it is best to leave them in this folder as it allows the editor to locate the related metadata files.
Right-click the project name and select Add translation Languages... from the Solution explorer window. This brings up the dialog for adding .xlf based languages. Any existing .xlf based languages that are discoverable by the Toolkit will have the selection box pre-checked to indicate that the language is already included the project.
My .xlf file is not included in the list of files processed by the Toolkit during build.
If an .xlf file is excluded, and then re-included in a project, the file type element may be set incorrectly. To check for this condition, open the project file directly and look at the .xlf file's include type. The type element must be set to "None" for the Toolkit to process the file. If it is set to "Content" or another value, change it to "None". Save the project file and reload the project.
Example: German (Germany).xlf type is incorrect:
<Content Include="MultilingualResources\German (Germany).xlf" />
<None Include="MultilingualResources\Pseudo Language %28Pseudo%29.xlf" />
I've added .xlf-based languages. Where are my strings?
The language(s) you selected are added in the "MultilingualResources" folder. Language files are empty when initially created. Strings from your .resjson files are populated into these .xlf files during the next rebuild.
When I build my project the .xlf files remain empty.
Try these steps:
- Use Rebuild to ensure the .xlf files are updated. Visual Studio optimizes the Build command to build only files that have changed since the last Build. Visual Studio does not detect changes when new .xlf files are added.
- Ensure that your app supports the Windows Store app globalization and localization design model. Refer to the other topics of Globalizing your app.
Adding Languages to Your App
What is Microsoft Translator Service?
Microsoft Translator is a cloud-based service that provides machine-based translation. Machine translation is ideal for gaining access to translation when human translation is not reasonable to obtain. You can learn more at Microsoft Translator.
The Toolkit uses the Microsoft Translator service to provide translation suggestions for developers. You can see which languages are supported by Microsoft Translator when the Microsoft Translator icon is present in the Add Translation Languages window.
You can quickly translate your app using Microsoft Translator from within the Multilingual Editor by selecting a string and clicking the Translate button.
Pseudo Language.
Pseudo Language is an artificial modification of the software product that simulates real language localization, but which remains readable to native speakers. Pseudo translation replaces characters and expands the resource string length to detect potential localizability issues or bugs early in the project cycle and before the actual localization starts. For more details about localizability testing with Pseudo Language, see Localizability Testing.
What are Pseudo Resource Trackers?
In addition to character replacement and expansion, the pseudo engine provides a unique tracking identifier for each resource. This tracker is prepended to the start of every string and enclosed within brackets [xxxxx]. You can use these trackers during visual UI inspection testing. They can help track down specific resources in the product, especially if multiple resources have similar or duplicate text.
In the following "Hello World" text example, the pseudo translation expands to take about 30% more screen space, and then applies the resource tracker:
"Hello World" -> "Ĥèĺļõ Ŵòŗłđ" -> "[!!_Ĥèĺļõ Ŵòŗłđ_!!]" -> “[hJ8s1][!!_Ĥèĺļõ Ŵòŗłđ_!!]"
Resource trackers are on by default, and can be seen in the PseudoSettings.config file under the attribute "EnableResourceTracker = true". This parameter can be changed to false if desired.
I can't find Pseudo Language in the Windows 8 Language Preference list.
English (qps-ploc) is not displayed by default in the Windows 8 language preferences list. To add English (qps-ploc):
- 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.
Testing
I'm not seeing any translations when I launch my app, or my app is only partially translated.
Ensure that your .xlf file contains translations.
Open the .xlf file in the Multilingual Editor to see if the translations are present. When strings in the .resjson or .resw file are updated, any related translations are removed. This is to ensure that the translation matches the related string. Translate the string and rebuild.
My strings are translated, but still don't show up in my app.
Use Rebuild to ensure that the updated .xlf file is included in your app's PRI file. Visual Studio optimizes the Build command to build only files that have changed since the last Build. The .xlf files currently do not automatically trigger the need to rebuild.
Check your language preference order.
Ensure that the language you are testing is listed at the top of the language preference list. The app displays languages in this order, and if your app default language is not at the top, you may never see your translations.
What kind of localizability issues can I find using Pseudo Language?
- UI truncations. Pseudo Language adds characters to your string to show you what your string might look like after translation.
- Hardcoded strings. If you see regular English text in your Pseudo Language app, you know that the string has been hardcoded and is not being translated by the Toolkit.
For more information about Pseudo Language and localizability testing using Pseudo Language, see Localizability Testing.
My app isn't being displayed according to my language preference.
Language preference is determined by how your languages are ordered, from top to bottom. Make sure the order is correct before you deploy your app. Open the Control Panel, select Clock, Language, and Region > Language, select a language, and click Move up or Move down to change the order.
The Toolkit is reporting an 0x80004004 error in the build output.
Message:
Merge of Loc PRI file failed calling makepri.exe: "0x80004004"
This can happen when the region format conflicts with the Toolkit build operation. The workaround is to change your region code to en-US while building.
The Toolkit is reporting an 0x80004005 error in the build output
Message:
Merge of Loc PRI file failed calling makepri.exe: "0x80004005"
This can happen when the .xlf file contains an unsupported target language. The Multilingual App Toolkit Customer Preview incorrectly used the target culture "zh-cht" for Chinese Traditional and "zh-chs" for Chinese Simplified. This has been corrected from previous releases.
To correct this error, manually modify the .xlf files that contain the incorrect codes. Change "zh-cht" to "zh-hant" and "zh-chs" to "zh-hans".
Is there a way to find out more information about the errors I'm seeing?
Yes, you can turn on verbose logging in Visual Studio. Select the Tools > Options menu to display the Options dialog. Next, expand Projects and Solutions and select Build and Run. Change the MSBuild project build output verbosity from Minimal to Normal or higher.
Note Running msbuild from the command line can also produce additional messages. Try building the project from the Visual Studio command line:
msbuild /t:rebuild <projectname>
Importing/Exporting XLIFF files
Import translation failed
Import performs basic validation before importing to ensure target culture information matches between the existing .xlf and the .xlf that is being imported. Open the .xlf files in the Multilingual Editor and make sure the culture information matches.
What if my translator doesn't have Windows 8 / Visual Studio / Multilingual App Toolkit installed?
That's ok! When you select Send for translation, the email includes a link to download and install the Multilingual App Toolkit. Without Windows 8 and Visual Studio, the Multilingual Editor is the only installable component.
Once the translation files are ready and returned to you, right-click the .xlf file and select Import Translations, and select the returned .xlf file.
Deprecated features
What happened to the MarkupRules.xml and ResourcesLocks.xml files?
The released version of the Multilingual App Toolkit no longer uses proprietary resource locking files. Instead, the XLIFF 1.2 tag <mrk> is added directly to the .xlf file to identify strings that are not modified during Machine Translation. This enables the XLIFF file to be self-contained, and allows for per-file based resource locking.
As a result, these extra support files are no longer needed and they can be safely deleted from projects created with an earlier version of the Toolkit.
What happened to the .TPX file?
The .TPX file provided an easy way to include the MarkupRules.xml and ResourcesLocks.xml files when the .xlf file was sent out for translation. With the removal of the two support files, this functionality is no longer required.
If you have translations in a .TPX file that you need to retrieve, simply rename the .TPX file extension to .ZIP. This will allow you to open and extract the contents with File Explorer or any .ZIP compatible tool.
Other questions
I think I've done everything right, it still isn't working.
Try these steps:
Add translations using one of the methods described above.
Dump the .pri file (documented in MakePRI.exe configuration) to see if your translations are in the .pri file. Translations will appear with language code and translated value:
<Candidate qualifiers="Language-QPS-PLOC" type="String"> <Value>[!!_Ŝéãřćĥ_!!]</Value> </Candidate>Build from a cmd prompt; the resulting error may have more details than what is reported in the build output.
I enabled my app using the Multilingual App Toolkit for Visual Studio 11 Beta or RC. Do I need to do anything special?
Yes. Once you have the Multilingual App Toolkit v1.0 installed, you need to disable and then enable the Multilingual App Toolkit using the Tools menu. This will update the project to work with the newer version of the Toolkit.
I installed Windows 8 and Visual Studio 2012, and the Multilingual App Toolkit for Visual Studio 11 Beta.
If you used Programs and Features to uninstall the Multilingual App Toolkit, the Release Preview of the Toolkit still won't install because the extension is still installed in Visual Studio.
To fix this, run Visual Studio and uninstall the Multilingual App Toolkit extension via the Extension Manager.
My app failed certification to the Windows Store.
Ensure that your app contains only supported languages. Before starting the certification process, you should exclude the Pseudo Language (Pseudo).xlf file from your project. Pseudo Language is not a language selectable by the Windows Store and including it provides no value to your customers.