Guidelines and checklist for globalizing your app (Windows Store apps using C#/VB/C++ and XAML)

Describes best practices for globalizing your apps to a wider audience or market and for localizing your apps for a specific audience or market.

Guidelines for internationalization

Whether you localize your UI or not, consider an international market when you select UI terms and images. This saves time and cost for the markets you do localize to. Customers who use a version that isn't localized in their native language will understand your UI more easily.

The following table presents the practices recommended for internationalizing your apps.


Use the correct formats for numbers, dates, times, addresses, and phone numbers.

The formatting used for numbers, dates, times, and other forms of data varies between cultures, regions, languages, and markets. If you're displaying numbers, dates, times, or other data, use globalization APIs to get the format that the user prefers.

For more info, see Quickstart: Using global-ready formats.

Support international paper sizes.

The most common paper sizes differ between countries, so if you include features that depend on paper size, like printing, be sure to support and test common international sizes.

Support international units of measurement and currencies.

Different units and scales are used in different countries, although the most popular are the metric system and the imperial system. If you deal with measurements, like length, temperature, or area, get the correct system measurement by using the Globalization namespace. If your app supports displaying currencies, make sure you use the correct formatting. You can also get the currency for the user’s geographic region by using the CurrenciesInUse property.

Display text and fonts correctly.

The ideal font, font size, and direction of text varies between different markets.

For more info, see How to adjust layout for RTL languages and localize fonts.

Use Unicode for character encoding.

By default, recent versions of Microsoft Visual Studio use Unicode character encoding for all documents. If you're using a different editor, be sure to save source files in the appropriate Unicode character encodings. All Windows Runtime APIs return UTF-16 encoded strings.

Record the language of input.

When your app asks users for text input, record the language of input. This ensures that when the input is displayed later it's presented to the user with the appropriate formatting. Use the CurrentInputMethodLanguage property to get the current input language.

Don't use language to assume a user's location, and don't use location to assume a user's language.

In Windows, the user's language and location are separate concepts. A user can speak a particular regional variant of a language, like en-gb for English as spoken in Great Britain, but the user can be located in an entirely different country or region. Consider whether your apps require knowledge about the user's language, like for UI text, or location, like for licensing issues.

For more info, see How to manage language and region.

Avoid colloquialisms and metaphors.

Language that's specific to a demographic, such as culture and age, can be hard to understand or translate, because only people in that demographic use that language. Similarly, metaphors might make sense to one person but mean nothing to someone else. For example, a "bluebird" means something specific to those who are part of skiing culture, but those who aren’t part of that culture don’t understand the reference. If you plan to localize your app and you adopt an informal voice or tone, be sure that you adequately explain to localizers the meaning and voice to be translated.

Don't use technical jargon, abbreviations, or acronyms.

Technical language is less likely to be understood by non-technical audiences or people from other cultures or regions, and it's difficult to translate. People don't use these kinds of words in everyday conversations. Technical language often appears in error messages to identify hardware and software issues. At times, this might be be necessary, but you should rewrite strings to be non-technical.

Avoid images that might be offensive.

Images that might be appropriate in your own culture may be offensive or misinterpreted in other cultures. Avoid use of religious symbols, animals, or color combinations that are associated with national flags or political movements.

Avoid political offense in maps or when referring to regions.

Maps may include controversial regional or national boundaries, and they're a frequent source of political offense. Be careful that any UI used for selecting a nation refers to it as a "country/region". Putting a disputed territory in a list labeled "Countries", like in an address form, could get you in trouble.

Don't use string comparison by itself to compare language tags.

BCP-47 language tags are complex. There are a number of issues when comparing language tags, including issues with matching script information, legacy tags, and multiple regional variants. The resource management system in Windows takes care of matching for you. You can specify a set of resources in any languages, and the system chooses the appropriate one for the user and the app.

Don't assume that sorting is always alphabetic.

For languages that don't use Latin script, sorting is based on things like pronunciation, number of pen strokes, and other factors. Even languages that use Latin script don't always use alphabetic sorting. For example, in some cultures, a phone book might not be sorted alphabetically. The system can handle sorting for you, but if you create your own sorting algorithm, be sure to take into account the sorting methods used in your target markets.


Guidelines for localization

The following table presents the practices recommended for adapting your app for a specific language, region, market, or audience.


Separate resources such as UI strings and images from code.

Design your apps so that resources, like strings and images, are separated from your code. This enables them to be independently maintained, localized, and customized for different scaling factors, accessibility options, and a number of other user and machine contexts.

Separate string resources from your app's code to create a single language-independent codebase. Always separate strings from app code and markup. and place them into a resource file, like a ResW or ResJSON file.

Use the resource infrastructure in Windows to handle the selection of the most appropriate resources to match the user's runtime environment. For more info, see Guidelines for app resources.

Isolate other localizable resource files.

Take other files that require localization, like images that contain text to be translated or that need to be changed due to cultural sensitivity, and place them in folders tagged with language names.

Set your default language, and mark all of your resources, even the ones in your default language.

Always set the default language for your apps appropriately. The default language determines the language that's used when the user doesn't speak any of the supported languages of the app. Mark default language resources, for example en-us/Logo.png, with their language, so the system can tell which language the resource is in and how it's used in particular situations.

Determine the resources of your app that require localization.

What needs to change if your app is to be localized for other markets? Text strings require translation into other languages. Images may need to be adapted for other cultures. Consider how localization affects other resources that your app uses, like audio or video.

Use resource identifiers in the code and markup to refer to resources.

Instead of having string literals or specific file names for images in your markup, use references to the resources. For XAML, see [link], for HTML see link. Be sure to use unique identifiers for each resource.

Enable text size to increase.

Allocate text buffers dynamically since text size may expand when translated. If you must use static buffers, make them extra-large (perhaps doubling the length of the English string) to accommodate potential expansion when strings are translated. There also may be limited space available for a user interface. To accommodate localized languages, ensure that your string length is approximately 40% longer than what you would need for the English language. For really short strings, such as single words, you may needs as much as 300% more space. In addition, enabling multiline support and text-wrapping in a control will leave more space to display each string.

Support mirroring.

Text alignment and reading order can be left-to-right, as in English, or right-to-left (RTL), as in Arabic or Hebrew. If you are localizing your product into languages that use a different reading order than your own, be sure that the layout of your UI elements supports mirroring. Even items such as back buttons, UI transition effects, and images may need to be mirrored.

For more info, see How to adjust layout for RTL languages and localize fonts.

Reduce localization costs.

Reduce localization costs by avoiding use of text in images or speech in audio files. If you're localizing to a language with a different reading direction than your own, using symmetrical images and effects make it easier to support mirroring.

Use short strings.

Shorter strings are easier to translate and enable translation recycling. Translation recycling saves money because the same string isn't sent to the localizer twice.

Strings longer than 8192 characters may not be supported by some localization tools, so keep string length to 4000 or less.

Provide strings that contain an entire sentence.

Provide strings that contain an entire sentence, instead of breaking the sentence into individual words, because the translation of words may depend on their position in a sentence. Also, don't assume that a phrase with multiple parameters will keep those parameters in the same order for every language.

Comment strings.

Ensure that strings are properly commented, and only the strings that need to be translated are provided to localizers. Over-localization is a common source of problems.

Don't re-use strings in different contexts.

Don't re-use strings in different contexts, because even simple words like "on" and "off" may be translated differently, depending on the context.


Security Considerations

The following articles provide guidance for writing secure C++ code.

Related topics

Quickstart: Using global-ready formats
How to adjust layout for RTL languages and localize fonts
Guidelines for app resources
How to manage language and region