@amazon-devices/asset-resolver-lib

The AssetResolver API allows apps to retrieve localized string resources matching the device locale, so that users see UI messages in the expected language. These assets are resolved based on various system qualifiers such as locale, day/night mode, and UI mode. Assets can be text-based, images, or raw files.

Remarks

Asset Resolution

The AssetResolver library provides apps a means of seamless asset resolution whereby assets are ranked according to device system qualifiers. Apps can contain assets which are files that can be used for things such as images and text. AssetResolver supports images, raw files, and text-defining files.

Assets must be located in the application's assets directory, and the following directory structure must be followed.

└── assets
    ├── image
    ├── raw
    └── text

For text localization, Asset Resolver expects text asset files to use the puff.json format for defining string and numeric values. PUFF-J files define text resources used in an application and are used by Asset Resolver in its getString() and getNumber() methods.

Configuration Qualifiers

The AssetResolver's methods resolve assets based on the system's current configuration qualifiers. These are values which define certain device properties such as locale, UI mode, and so on.

For example, the locale qualifier can take values such as en-US, es-AR, or es-SP. This qualifier directly influences which assets are resolved. In the following asset directory structure, the file strings.puff.json is defined in multiple directories: one for each locale and one in text to act as a default.

└── assets
    ├── image
    ├── raw
    └── text
        ├── en
        │   └── strings.puff.json
        ├── en-US
        │   └── strings.puff.json
        ├── es
        │   └── strings.puff.json
        ├── es-AR
        │   └── strings.puff.json
        └── strings.puff.json

Depending on the current system configuration qualifiers, the AssetResolver resolves text based on the most appropriate match; if there is none, the default file is used.

NOTE: When an app supports a locale (such as en-GB), it must also define support for that locale's default qualifier (in this case en). Defining a default asset file is recommended as it ensures there is always an asset matched in case asset resolution fails.

If the system configuration qualifier for locale is es-AR, then the file assets/text/es-AR/strings.puff.json is chosen when using the AssetResolver API. If multiple locales contain the same text assets, symbolic links to a single asset file can be used to save device storage space.

NOTE: Only locale is supported as a configuration qualifier to resolve assets around.

Access Control

The AssetResolver methods are not access-controlled. AssetResolver methods only execute within an app's subset of the device's filesystem. Moreover, other apps cannot explicitly resolve assets from another app, ensuring app-to-app isolation.

Get started

Add the following library dependency to the dependencies section of your package.json file.

    "@amazon-devices/asset-resolver-lib": " ~2.0.0"

Usage

AssetConfiguration type

Certain APIs take in an AssetConfiguration object. This object is used to specify which qualifiers should be used when resolving assets. Currently locale is supported.

Retrieve an internationalized string value

To retrieve an internationalized string value, use the getString() method. This method takes in the identifier of the string being queried and an optional configuration object which specifies which qualifiers to use in asset resolution.

On failure, the method throws an Error whose message indicates the error condition.

const stringResult = AssetResolver.getString('welcome-string');

console.log('string value: {}', stringResult.value);
console.log('string direction: {}', stringResult.dir);

const config = { locale: 'fr-CA' };
const stringConfigResult = AssetResolver.getString('welcome-string', config);

console.log('string value: {}', stringConfigResult.value);
console.log('string direction: {}', stringConfigResult.dir);

Retrieve an internationalized number value

To retrieve an internationalized number value, use the getNumber() method. Similar to getString(), the method takes in a string which is the identifier for the number value being queried. Furthermore, the method also takes in an optional configuration object which specifies which qualifiers should to use asset resolution.

This method throws an Error if there is an issue in execution.

const numberResult = AssetResolver.getNumber('numeral');

console.log('number value: {}', numberResult);

const config = { locale: 'en-US' };
const numberConfigResult = AssetResolver.getNumber('numeral', config);

console.log('number value: {}', numberConfigResult);

Modules

• AssetResolver
• native-asset-resolver
• types/AssetResolverTypes

Last updated: Sep 30, 2025