Events
Mar 17, 9 PM - Mar 21, 10 AM
Join the meetup series to build scalable AI solutions based on real-world use cases with fellow developers and experts.
Register nowThis browser is no longer supported.
Upgrade to Microsoft Edge to take advantage of the latest features, security updates, and technical support.
This section describes the best practices to follow when developing world-ready applications.
Make your application Unicode internally.
Use the culture-aware classes provided by the System.Globalization namespace to manipulate and format data.
Use the culture property settings provided by the System.Globalization.CultureInfo class in the appropriate situations. Use the CultureInfo.CurrentCulture property for formatting tasks, such as date and time or numeric formatting. Use the CultureInfo.CurrentUICulture property to retrieve resources. Note that the CurrentCulture
and CurrentUICulture
properties can be set per thread.
Enable your application to read and write data to and from a variety of encodings by using the encoding classes in the System.Text namespace. Do not assume ASCII data. Assume that international characters will be supplied anywhere a user can enter text. For example, the application should accept international characters in server names, directories, file names, user names, and URLs.
When using the UTF8Encoding class, for security reasons, use the error detection feature offered by this class. To turn on the error detection feature, create an instance of the class using the constructor that takes a throwOnInvalidBytes
parameter and set the value of this parameter to true
.
Whenever possible, handle strings as entire strings instead of as a series of individual characters. This is especially important when sorting or searching for substrings. This will prevent problems associated with parsing combined characters. You can also work with units of text rather than single characters by using the System.Globalization.StringInfo class.
Display text using the classes provided by the System.Drawing namespace.
For consistency across operating systems, do not allow user settings to override CultureInfo. Use the CultureInfo
constructor that accepts a useUserOverride
parameter and set it to false
.
Test your application functionality on international operating system versions, using international data.
If a security decision is based on the result of a string comparison or case change operation, use a culture-insensitive string operation. This practice ensures that the result is not affected by the value of CultureInfo.CurrentCulture
. See the "String Comparisons that Use the Current Culture" section of Best Practices for Using Strings for an example that demonstrates how culture-sensitive string comparisons can produce inconsistent results.
For any element being used for interchange (for example, a field in a JSON document in an API call) or storage, use the CultureInfo; additionally, you should explicitly specify a roundtrip format (such as the "O"
, "o"
date-time format specifier). Although the format strings for the invariant culture are stable and unlikely to change, specifying an explicit format string helps to clarify the intent of your code.
Globalization data is not stable, and you should write your application and its tests with this in mind. It's updated several times a year through host OS channels on all supported platforms. This data is typically not distributed with the runtime.
Move all localizable resources to separate resource-only DLLs. Localizable resources include user interface elements, such as strings, error messages, dialog boxes, menus, and embedded object resources.
Do not hardcode strings or user interface resources.
Do not put non-localizable resources into the resource-only DLLs. This confuses translators.
Do not use composite strings that are built at run time from concatenated phrases. Composite strings are difficult to localize because they often assume an English grammatical order that does not apply to all languages.
Avoid ambiguous constructs such as "Empty Folder" where the strings can be translated differently depending on the grammatical roles of the string components. For example, "empty" can be either a verb or an adjective, which can lead to different translations in languages such as Italian or French.
Avoid using images and icons that contain text in your application. They are expensive to localize.
Allow plenty of room for the length of strings to expand in the user interface. In some languages, phrases can require 50-75 percent more space than they need in other languages.
Use the System.Resources.ResourceManager class to retrieve resources based on culture.
Use Visual Studio to create Windows Forms dialog boxes so they can be localized using the Windows Forms Resource Editor (Winres.exe). Do not code Windows Forms dialog boxes by hand.
Arrange for professional localization (translation).
For a complete description of creating and localizing resources, see Resources in .NET apps.
Tip
The following best practices are for ASP.NET Framework apps. For ASP.NET Core apps, see Globalization and localization in ASP.NET Core.
Explicitly set the CurrentUICulture and CurrentCulture properties in your application. Do not rely on defaults.
Note that ASP.NET applications are managed applications and therefore can use the same classes as other managed applications for retrieving, displaying, and manipulating information based on culture.
Be aware that you can specify the following three types of encodings in ASP.NET:
requestEncoding
specifies the encoding received from the client's browser.responseEncoding
specifies the encoding to send to the client browser. In most situations, this encoding should be the same as that specified for requestEncoding
.Specify the values for the requestEncoding
, responseEncoding
, fileEncoding
, culture
, and uiCulture
attributes in the following three places in an ASP.NET application:
uiCulture
, culture
, and responseEncoding
can be specified in a page directive.fileEncoding
and requestEncoding
. Only uiCulture
, culture
, and responseEncoding
can be specified in the application code.Note that the uiCulture value can be set to the browser accept language.
For applications that are distributed, allow zero-downtime updates (for example, Azure Container Apps), or similar you must plan for situations where there may be multiple instances of the application with different format rules or other culture data, most relevantly time zone rules.
To make dependencies more explicit and testing potentially easier and parallelizable, you should consider explicitly passing culture-relevant settings, such as CultureInfo
parameters, to methods that perform formatting, and TimeZoneInfo
to methods that work with dates and times. You should also use TimeProvider or a similar type when retrieving the time.
For most tests, you shouldn't explicitly validate the exact output of a given formatting operation or the exact offset of a time zone. Formatting and time zone data may change at any time and may differ between two otherwise identical instances of an operating system (and potentially different processes on the same machine). Relying on an exact value makes tests brittle.
CultureInfo
object with its constructor new CultureInfo(..)
and setting the DateTimeFormat
and NumberFormat
properties. For more complicated cases, subclassing the type allows overriding additional properties. There are potential additional benefits to this, such as enabling pseudolocalization with resource files.TimeZoneInfo
instance during test setup. There are potential additional benefits to this, such as enabling stable testing of certain edge cases (for example, changes to DST rules)..NET feedback
.NET is an open source project. Select a link to provide feedback:
Events
Mar 17, 9 PM - Mar 21, 10 AM
Join the meetup series to build scalable AI solutions based on real-world use cases with fellow developers and experts.
Register nowTraining
Learning path
Use advance techniques in canvas apps to perform custom updates and optimization - Training
Use advance techniques in canvas apps to perform custom updates and optimization
Documentation
Learn more about: Globalization
Learn the concepts of localization while learning how to use the IStringLocalizer and IStringLocalizerFactory implementations in your .NET workloads.
Learn about localizability reviews, and when they should occur and how to use them.
Globalize and localize .NET applications - .NET
Learn how to develop a world-ready application. Read about globalization, localizability review, and localization in .NET.