How to name resources using qualifiers (XAML)

Article
08/31/2015

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.

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.png

Then, a user who prefers English (United States) on a Scale 140 machine 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.

Language (application language)

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 application language list. Changes to the application 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-80 (only valid for resources specified in the app manifest)
scale-100
scale-140
scale-180

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.

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.

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.

Examples:

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

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").

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.

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 DX 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.

Format 1: