How to load string resources (HTML)
[ This article is for Windows 8.x and Windows Phone 8.x developers writing Windows Runtime apps. If you’re developing for Windows 10, see the latest documentation ]
You can load string resources from objects such as resource files, libraries, controls, and 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 apps need only a single default resource file per language (<language>/Resources.resjson), and they can refer to their resources by using a relative path to keys within that file (for example /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
A reference from markup:
<span data-win-res="{textContent: '/Errors/AlreadyRegistered'}"></span>
A reference from code:
WinJS.Resources.getString('/Errors/AlreadyRegistered');
The resource identifier is of the form /ResourceFileNameStringName. 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 and controls
Apps often have multiple components, or take dependencies on libraries such as .NET portable class libraries, other compatible class libraries, and control libraries.
Whenever possible, controls and libraries 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:
ClassLibraryOrAssemblyName/ResourceFileName/StringName
Programmatically, libraries can also get their own ResourceLoader for their resources. For example, the following code illustrates how a library can get a ResourceLoader for its own resource file:
var resources = Windows.ApplicationModel.Resources;
var RL = new resources.ResourceLoader('ContosoControl/Resources');
RL.getString('loadingStr'); // which came from ContosoControl's Resources
Loading strings from other packages
Resources for each app package are separately managed and accessed through separate top level ResourceMap object that are accessible from the current ResourceManager. Within each package, various components can have their own ResourceMap Subtree values.
Framework packages can access their own resources with a more absolute resource identifier URI:
For more details on ms-resource URIs, see URI schemes.
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 Windows Runtime 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 identifier 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 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 data (this is usually done in the Visual Studio tabbed UI for editing the appxmanifest). For example, For example, ms-resource:String1 refers to a string called String1 in the Resources.resw resource file, while ms-resource:/ManifestStrings/Shortname refers to a string called Shortname in the ManifestStrings.resw 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.
See How to name resources using qualifiers for details on the various qualifiers.
The ResourceManager maintains the default context object against which resource lookups are performed. In some cases, being explicit about the language, scale or other context qualifier when the app loads resources is 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, where the Languages property is deliberately overridden:
var rcns = Windows.ApplicationModel.Resources.Core;
var context = new rcns.ResourceContext(); // deliberately not using getForCurrentView()
context.languages = new Array('fr-fr');
var resourceMap = rcns.ResourceManager.current.mainResourceMap.getSubtree('Resources');
var str = resourceMap.getValue('string1', context).ValueAsString;
Another technique you can use is to call ResourceContext.SetGlobalQualifierContext before calling ResourceContext.GetForCurrentView. For the language scenario you'd set the language qualifier to a new value. The difference if you do this is that the qualifier and context change now applies to all resource lookups, not just the specific ResourceContext you created for use for the single GetValue call. See also ApplicationLanguages.PrimaryLanguageOverride.
Events and context changes
An app might still be running when the system changes. This results in a different set of qualifiers being used. One such change is if 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 the addEventListener method:
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
Features and restrictions by context