Quickstart: Using string resources (XAML)

Put string resources into resource files, and reference those strings from your code or markup.

Instructions

1. Put strings into resource files instead of putting them directly in code or markup.

   1. Open package.appxmanifest in Visual Studio, go to the Application tab, and set your default Language to "en-US". If this is a universal app, do this for each package.appxmanifest in your solution.

      Note  This specifies the default language for the project. The default language resources are used if the user's preferred language or display languages do not match the language resources provided in the application.

       

   2. Create a resource file in a subfolder that is specific to a language. For the resource file, we recommend that you use the default file name. Apps can partition their resources into other files, but must be careful to refer to them correctly (see How to load string resources).

      C# and VB

      1. In the Solution Explorer, right-click the project (the Shared project if this is a universal app) and select Add > New Folder.
      2. Name the new folder "Strings".
      3. Create a sub-folder and a resource file for English (United States).
         1. Right-click the Strings folder and add a new folder beneath it. Name it "en-US". The resource file is placed in a folder that has been named for the BCP-47 language tag. See How to name resources using qualifiers for details on the language qualifier and a list of common language tags.
         2. Right-click the en-US folder and select Add > New Item….
         3. Select "Resources File (.resw)".
         4. Click Add. This adds a resource file with the default name "Resources.resw".
         5. If you have .resx files with only string resources from previous .NET projects, select Add > Existing Item…, add the .resx file, and rename it to .resw.

      C++

      1. Right click the project item in Solution Explorer and select Add > New Item….
      2. Select Resources File (.resw) and in the Location text box, specify <ProjectRootPath>\Strings\en-US to create a subfolder to hold US English strings.

2. Open the file and use the editor to add two new resources:

   Strings/en-US/Resources.resw

   

   In this example, "Greeting" and "Farewell" are the keys used to identify the resource strings. "Greeting.Text" and "Greeting.Width" identify specific properties supported by the referencing controls. The comments are a good place to provide any special instructions to translators who localize the strings to other languages.

Note about Property identifiers:

The resource Name can only be qualified with property identifiers supported by all controls that reference the resource. If a property specified in the resource file cannot be assigned to a referencing control, a runtime exception occurs.

The [**GetString**](https://msdn.microsoft.com/en-us/library/BR206017) method cannot retrieve resources qualified with a property identifier. In this example, `GetString("Farewell")` returns "Goodbye", while `GetString("Greeting.Text")` and `GetString("Greeting")` both fail.

3. Associate controls to resources.

   You need to associate every control that needs localized text with the .resw file. You do this using the x:Uid attribute on your XAML elements like this:

   <TextBlock x:Uid="Greeting" Text="" />
   

   For the resource name, you give the Uid attribute value, plus you specify what property is to get the translated string (in this case the Text property). You can specify other properties/values for different languages such as Greeting.Width, but be careful with such layout-related properties. You should strive to allow the controls to lay out dynamically based on the device's screen.

   Note that attached properties are handled differently in resw files such as AutomationPeer.Name. You need to explicitly write out the namespace like this:

   MediumButton.[using:Windows.UI.Xaml.Automation]AutomationProperties.Name
   

4. Add string resource identifiers to code and markup.

   In your code, you can dynamically reference strings:

   var loader = new Windows.ApplicationModel.Resources.ResourceLoader();
   var str = loader.GetString("Farewell");
   

   auto loader = ref new Windows::ApplicationModel::Resources::ResourceLoader();
   auto str = loader->GetString("Farewell");
   

For more details on adding additional languages and localization, see Quickstart: Translating UI resources.

Related topics

How to name resources using qualifiers

How to load string resources

Quickstart: Translating UI resources

Roadmap for Windows Runtime apps using C# or Visual Basic

The BCP-47 language tag