How to name resources using qualifiers (HTML)

Article
01/11/2016

[ 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 name resources by using qualifiers. The qualifiers identify the context in which a version of a resource should be used.

Resource qualifiers

You can tailor your file and string resources to support multiple display scales, UI languages, high contrast settings, and more. Resource qualifiers are folder and filename modifiers that identify the context in which a particular version of a resource should be used.

The standard naming convention is

foldername/qualifiername-value_qualifiername-value/filename.qualifiername-value_qualifiername-value.ext

For example,

Images/en-US/homeregion-USA/logo.scale-100_contrast-white.png

is loaded by referring to

Images/logo.png

Note We recommend that you mark the default language on string resource files (such as en-US\resources.resw) and the default scale on images (such as logo.scale-100.png), even if these files will not be localized nor multiple resolution images provided.

Entire folder names are parsed for qualifiers. The folder names are then matched to a set of qualifiers or are considered part of the logical file path. The dotted segment in the file just before the file extension is considered a token that indicates qualifiers. Multiple qualifiers are separated by an underscore, and qualifiers are traditionally specified with their name and value (except language when used in a folder name).

App developers may choose to use either folder or file names to specify assets for a given set of contexts, or a mix of the two strategies depending on their workflow and the app's needs.

The correct resource is automatically chosen at run time based on each resource's qualifier and the current context. For example, you might provide the following assets:

en-us\logo.scale-100.png
en-us\logo.scale-140.png
fr-fr\logo.scale-100.png
fr-fr\logo.scale-140.png

Then, a user who prefers English (United States) on a Scale 140 display will see the en-us\logo.scale-140.png image. For details on resource selection in more complex fallback scenarios, see Resource Context.

The remaining sections of this topic detail the set of qualifiers and their possible values for each dimension supported by the resource infrastructure.

Important The formats described here are for within the qualifier segment of a filename (or the folder name in the languages case). The one or more qualifiers should all appear as a segment within the complete filename that comes after the resource name, and before the file extension, as per this mostly-placeholder format: name.qualifiers.ext The dots (.) here are important because they provide the syntax separator between the segments. You can't use a dot character otherwise within any of the qualifier formats.

Language (app)

The language qualifier specifies the BCP-47 language of the resource. Filenames require the lang or language qualifier, along with the language tag, but folders only need the language tag. For a list of languages, see the IANA language subtag registry.

Folder name formats:

<Any BCP-47 language tag>
lang-<Any BCP-47 language tag>
language-<Any BCP-47 language tag>

Filename formats:

lang-<Any BCP-47 language tag>
language-<Any BCP-47 language tag>

Examples:

es-MX/resources.resw
language-de-DE/UI.resw
images/logo.lang-fr-FR.png

The language qualifier is matched against the app language list. Changes to the app language at run time are propagated as events (see ResourceContext.QualifierValues). An app does not need to set or override the language.

Scale

The scale qualifier specifies the scale factor of the resource. This is typically used for images viewed on a higher-DPI device or when the app is zoomed. The scale of a resource matches the value of Windows.Graphics.Display.DisplayProperties.ResolutionScale or the next-largest scaled resource. If you use the scale qualifier on a resource, you should not use the targetsize qualifier.

Scale qualifiers:

scale-80 (only valid for resources specified in the app manifest)
scale-100
scale-140
scale-180 (Windows)
scale-240 (Windows Phone)

Changes to the scale at run time are propagated as events (see ResourceContext.QualifierValues).

Contrast

The contrast qualifier specifies the contrast theme setting of the system. Standard is used when all high contrast themes are off. High is valid when in any high contrast mode. Black represents when images with a black background and white foreground are preferred. White represents when images with a white background and black foreground are preferred. High Contrast #1 and High Contrast #2 theme settings match the Black qualifier value.

contrast-standard
contrast-high
contrast-black
contrast-white

Home region

The home region qualifier represents the home location of the user. It is typically specified at Windows installation, and is accessible from the Control Panel. This qualifier (ResourceContext.QualifierValues) is commonly overridden if some other data provider is known for location. The value can be any valid BCP-47 region tag, that is, any iso-3166-1 alpha 2 two-letter region code, plus the set of iso-3166-1 numeric three-digit geographic codes for composed regions (see United Nations Statistic Division M49 composition of region codes.) Note that codes for "Selected economic and other groupings" are not valid.

Home region format:

homeregion-<Region Code>

Examples:

homeregion-us
homeregion-jp
homeregion-419

The home region qualifier matches any parent composed region.

Target size

The targetsize qualifier can specify resources at a particular size (in pixels). It is primarily used to specify file type association icons or protocol icons shown in the desktop Windows Explorer. This qualifier is typically used for square images or icons and specifies only a single image dimension. The system or app requesting the resource (ResourceContext.QualifierValues) must explicitly specify a targetsize. There is no default. If you use the targetsize qualifier on a resource, you should not use the scale qualifier.

Targetsize format:

targetsize-<any positive integer>

Examples:

targetsize-16
targetsize-96

The targetsize context matches the next largest qualified resource.

Layout direction

Use the layout qualifier to specify resources that apply the directionality of specific reading order and text alignment. For example, an image may need to be mirrored for a right-to-left language such as Arabic or Hebrew. Most apps can use automatic flipping mechanisms to mirror images at run time; however, this qualifier is for cases where simple flipping isn't adequate. For more information, see How to adjust layout for RTL languages and localize fonts.

Layout direction format:

layoutdir-LTR
layoutdir-RTL
layoutdir-TTBLTR
layoutdir-TTBRTL

Configuration

Use the configuration qualifier to specify resources applicable only to a given authoring-time environment, such as test-only resources. Most app developers should not expect to use this. The environment variable MS_CONFIGURATION_ATTRIBUTE_VALUE may be set to the string value which has been assigned to the relevant resources (such as test).

Configuration format:

config-<MS_CONFIGURATION_ATTRIBUTE_VALUE>

Examples:

config-test
config-designer

Alternate form

The alternate form qualifier may be used to provide an alternate form of a resource for some special purpose. This is typically used only by Japanese app developers to provide a furigana string, for which the value msft-phonetic is reserved. The system or app must provide a value to use this qualifier in particular situations. There is no default. Do not use the msft- prefix for your own custom values.

Alternate form Format:

altform-<Any string between 1 and 16 chars>

Examples:

altform-msft-phonetic
altform-myapp-special

DirectX feature level

The DirectX feature level qualifier represents the DirectX feature level of graphics adapters that will be used to render the resource. This is typically used for Direct3D display assets used in games. The DirectX feature level of a resource will match a value set explicitly on a Resource Context by the app. If a resource with exactly the same DirectX feature level value is not available, the resource with the next lowest value available will be used.

Note The DirectX feature level qualifier is supported starting in Windows 8.1.

There are two possible formats for the DirectX feature level qualifier. Supported values are DX9, DX10, and DX11.

DirectX feature level format

DXFeatureLevel-<value>
DXFL-<value>

Examples:

DXFeatureLevel-DX10
DXFL-DX11

Remarks

As mentioned before, any of these formats within the set of qualifiers can be combined if there's a need to support multiple qualifier patterns for the same resource scenario. The separator to use between qualifier patterns is the underscore character (_). For example, here is a path to a resource file that supports configuration, scale, and layout direction explicitly: logo.config-test_scale-100_layoutdir-LTR.png

Guidelines for scaling to pixel density

Supporting high contrast themes

How to manage language and region

How to adjust layout for RTL languages and localize fonts

How to prepare for localization

How to Assign a Custom Icon to a File Type

Adding Icons, Previews and Shortcut Menus

Windows.ApplicationModel.Resources.Core.ResourceContext.QualifierValues

Windows.Graphics.Display.DisplayProperties.ResolutionScale

External links

The BCP-47 language tag

IANA language subtag registry