Language: HTML | XAML

How to load string resources (XAML)

Applies to Windows and Windows Phone

You can load string resources from objects such as resource files, libraries, controls, and Windows Store app packages and manifests.

Loading strings from resource files.

String resources are authored in resource files and referred to by using resource identifiers. For a basic introduction to loading string resources, see Quickstart: Using string resources.

Most applications need only a single default resource file (<language>/Resources.resw), and they can refer to their resources by using a relative path ('String1'). But in some applications it is appropriate to separate resources into multiple resource files in order to provide separation of components.

For example:

Filename:

Strings/en-US/Errors.resw


<TextBlock x:Uid="/Errors/AlreadyRegistered"></TextBlock>



var res =  Windows.ApplicationModel.ResourceLoader('Errors');
res.GetString('AlreadyRegistered');

The resource identifier is of the form /ResourceFileName/StringName. Note that the resource filename does not include the extension or the folder path. Therefore all resource filenames need to be unique in a component or project.

Loading strings from libraries, controls, or software development kits (SDKs).

Apps often have multiple components, or take dependencies on libraries such as .NET portable libraries, class libraries, and control libraries.

Whenever possible, controls and software development kits (SDKs) should try to reduce the number of resources and rely on the app to provide them. When a library does need to provide resources, it should allow apps to replace those resources as an input. This may be necessary if the library does not have the same extent of localization as the app using it.

The control should display custom strings passed into it exactly as given and, where possible, let the app handle localization.

Components or library files are typically added into a subfolder of the package they are included in during the build process, similar to their string resources. Their resource identifier usually takes the following form:

ClassLibrarySDKOrAssemblyName/ResourceFileName/StringName

Programmatically, libraries can also get their own ResourceLoader for their resources. For example, the following code illustrates how a library or SDK can get a ResourceLoader for its own resource file:


ResourceLoader R = new Windows.ApplicationModel.Resources.ResourceLoader("ContosoControl/Resources");
R.getString("loadingStr"); // which came from ContosoControl's Resources.resw


Loading strings from other packages.

Resources for each Windows Store app package are separately managed and accessed through separate top level ResourceMaps that are accessible from the current ResourceManager. Within each package, various components can have their own ResourceMap Subtrees.

Framework packages can access their own resources with a more absolute resource identifier URI. For more details on ms-resource URIs, see ms-resource, ms-appx URIs.

Loading strings from the Windows Store app manifest.

All displayable strings and logos in the manifest are localizable. Logos can also be tailored for scale and high contrast mode. String references can be added in the place of a hardcoded string, by placing an ms-resource: scheme-specified URI into the manifest. For example,


<DisplayName>ms-resource:String1</DisplayName>

refers to a string called String1 in the Resources.resw or Resources.resjson resource file, while


ShortName="ms-resource:/ManifestStrings/Shortname"

refers to a string called Shortname in the ManifestStrings.resw/.resjson resource file.

Loading strings for a specific language or context.

The default ResourceContext, an object obtained from the ResourceManager, represents the current state to which resources are matched. The ResourceContext contains all the various qualifier values for the current user and machine. Although each qualifier can be overridden, it is not recommended that you override them. Most qualifiers have a system data provider, which in some cases is best altered through a separate API (that is, PrimaryLanguageOverride), or best left unchanged.

Windows.ApplicationModel.Resources.Core.ResourceManager.current.defaultContext;

See How to name resources using qualifiers for details on the various qualifiers and their data providers.

The ResourceManager maintains the default context object against which resource look-ups are done. In some particular cases, being explicit about the language, scale or other context qualifier when the app loads resources may be helpful. For example, an app might allow a user to select an alternative language for tooltips or error messages. Lookups can specify their own explicit overridden context object, to affect which resource is chosen. To specify an explicit context:


using Windows.ApplicationModel.Resources.Core;

var context = new ResourceContext();
context.languages = new List<String>();
context.languages.Add("en-us");

var resourceMap = ResourceManager.Current.MainResourceMap.GetSubtree("Resources");
var str = resourceMap.GetValue("scenario3Message", context);

Events and context changes.

Windows Store apps may still be running when the system changes. This results in a different set of qualifiers being used. One such change might be when the user turns on high contrast. Various system changes invoke events on the ResourceContext object.

In apps that use XAML, the process of updating the displayed page with new resources is complicated by the fact that handlers for these events are often called on a different thread than the UI thread. The following partial sample illustrates a way to listen for the change event and to update text on the main page. Note that:

  • In the MainPage constructor, the event handler qualifiers_MapChanged is set to be called when the resource qualifiers change.
  • The event handler qualifiers_MapChanged ensures that the method UpdateTextBlocks is called on the proper thread.
  • The method UpdateTextBlocks does the work of loading the newly appropriate resource strings and updating the text blocks on the main page.

public sealed partial class MainPage : SampleApp.Common.LayoutAwarePage
{
    public MainPage()
    {
        this.InitializeComponent();

        // Listen for event when the resource qualifiers change.
        var qualifiers = Windows.ApplicationModel.Resources.Core.ResourceManager.Current.DefaultContext.QualifierValues;
        qualifiers.MapChanged += new MapChangedEventHandler<string, string>(qualifiers_MapChanged);
    }

    // Event handler for change in resource qualifiers.
    private async void qualifiers_MapChanged(IObservableMap<string, string> sender, IMapChangedEventArgs<string> @event)
    {
        var d = GreetingHello.Dispatcher;
        if (d.HasThreadAccess)
        {
            UpdateTextBlocks();
        }
        else
        {
            await d.RunAsync(Windows.UI.Core.CoreDispatcherPriority.Normal, () => UpdateTextBlocks());
        }
    }

    // Update text blocks on the main page.
    private void UpdateTextBlocks()
    {
        // Replace the Text properties of text blocks on the main page with the appropriate resource strings.
        var resourceLoader = new Windows.ApplicationModel.Resources.ResourceLoader();
        Greeting.Text = resourceLoader.GetString("Greeting");
        Farewell.Text = resourceLoader.GetString("Farewell");
    }
    ...
}

Related topics

Windows.ApplicationModel.Resources.ResourceLoader
Windows.ApplicationModel.Resources.Core.ResourceContext
Windows.ApplicationModel.Resources.Core.ResourceManager
Windows.ApplicationModel.Resources.Core.ResourceMap
Windows.Globalization.ApplicationPreferences.PrimaryLanguageOverride
Features and restrictions by context
How to name resources using qualifiers
Roadmap for Windows Runtime apps using C# or Visual Basic

 

 

Show:
© 2014 Microsoft