Information
The topic you requested is included in another documentation set. For convenience, it's displayed below. Choose Switch to see the topic in its original location.

How to load string resources (HTML)

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.resjson), 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.resjson


<span data-win-res="{textContent: '/Errors/AlreadyRegistered'}"></span>


WinJS.Resources.getString('/Errors/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.

For example:


var rating = new WinJS.UI.RatingsControl(el, {label: 'Please Rate', image: 'images/star.png'});

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


var control = new Control(el, {commands: [
    {label: R.getString('Reply')}, 
    {label: R.getString('ReplyAll')
    ]});

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:


ResourceLoader R = new Windows.ApplicationModel.Resources.ResourceLoader('ms-resource://Microsoft.WinJS/ui');
R.getString('loadingStr'); // which came from Resources.resw/resjson in the Microsoft.WinJS package.

For more details on ms-resource URIs, see ms-resource, ms-appx URIs.

Loading strings from JavaScript controls.

JavaScript controls that provide default strings should utilize WinJS.Resources.getString to retrieve their own strings.

HTML documents that are loaded into the web context (with ms-app-web://) do not have access to WinRT APIs. Therefore, in JavaScript code, include JavaScript controls that have been written to use WinJS.Resources.getString. In the web context, WinJS.Resources.getString falls back to looking for the given id as a property of a global strings object.


var strings = { 'String1' : 'Hello' };
WinJS.Resources.getString('String1');

You can also override WinJS.Resources.getString to fetch resources from a different location.


WinJS.Resources.getString = function(id){
    return getStringFromOtherService(id);
}

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:


var resourceNS = Windows.ApplicationModel.Resources.Core;

var context = new resourceNS.ResourceContext();
context.languages = new Array('en-us');

var resourceMap = resourceNS.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 JavaScript, the simplest way to listen for these events is through


WinJS.Resources.addEventListener('contextchanged', refresh, false);

After detecting the event, apps can reprocess the document, so that the correct resources can be loaded.


function refresh(){
    WinJS.Resources.processAll(); // Refetch string resources.
}

Reprocessing resources may cause databound values within the resource to be reset as the new resource is applied directly to the element's property. If the resource contains databinding slots, be sure to rebind them when reprocessing.

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
WinJS.Resources.getString
Features and restrictions by context
How to name resources using qualifiers

 

 

Show:
© 2014 Microsoft