Connect and get help from 7,000+ developers on our Discord community.

Set localization options for Smart TV tests

Test localized versions of your Smart TV apps by configuring language and locale capabilities on BrowserStack App Automate.

BrowserStack App Automate lets you run your Smart TV tests in a specific language and locale. This is useful when your app changes its UI, content, currency, date format, or catalog based on the device’s language settings.

You control this from your test capabilities, no changes are needed on the device. BrowserStack sets the language at the start of the session and resets it during cleanup.

Some automations on Smart TV devices might fail when using non-English languages. Contact support if you are facing any issues.

Language and locale are supported on Amazon Fire TV, Nvidia Shield, Apple TV, and Roku.

Amazon Fire TV

Pass language as a two-letter lowercase ISO 639-1 code and locale as a two-letter uppercase ISO 3166-1 country code.

Capability	Description	Value
`language`	Sets the device language	two-letter lowercase ISO 639-1 code. Example: `fr`, `de`, `en`, `es`, `hi`
`locale`	Sets the regional locale	2-letter uppercase ISO 3166-1 country code. Example: `FR`, `DE`, `US`, `GB`, `IN`

Example:

DesiredCapabilities capabilities = new DesiredCapabilities();
capabilities.setCapability("platformName", "Android");
capabilities.setCapability("app", "bs://<your_app_hashed_id>");

HashMap<String, Object> bstackOptions = new HashMap<>();
bstackOptions.put("deviceName", "Amazon Fire TV Stick 4K");
bstackOptions.put("platformVersion", "7.1");
bstackOptions.put("projectName", "Smart TV Language Test");
bstackOptions.put("buildName", "Fire TV - French Locale");
bstackOptions.put("sessionName", "Fire TV fr_FR session");
capabilities.setCapability("bstack:options", bstackOptions);

capabilities.setCapability("language", "fr");
capabilities.setCapability("locale", "FR");

var capabilities = {
  'platformName': 'Android',
  'app': 'bs://<your_app_hashed_id>',
  'bstack:options': {
    'deviceName': 'Amazon Fire TV Stick 4K',
    'platformVersion': '7.1',
    'projectName': 'Smart TV Language Test',
    'buildName': 'Fire TV - French Locale',
    'sessionName': 'Fire TV fr_FR session'
  },
  'language': 'fr',
  'locale': 'FR'
}

desired_caps = {
  'platformName' => 'Android',
  'app' => 'bs://<your_app_hashed_id>',
  'bstack:options' => {
    'deviceName' => 'Amazon Fire TV Stick 4K',
    'platformVersion' => '7.1',
    'projectName' => 'Smart TV Language Test',
    'buildName' => 'Fire TV - French Locale',
    'sessionName' => 'Fire TV fr_FR session'
  },
  'language' => 'fr',
  'locale' => 'FR'
}

desired_caps = {
  'platformName': 'Android',
  'app': 'bs://<your_app_hashed_id>',
  'bstack:options': {
    'deviceName': 'Amazon Fire TV Stick 4K',
    'platformVersion': '7.1',
    'projectName': 'Smart TV Language Test',
    'buildName': 'Fire TV - French Locale',
    'sessionName': 'Fire TV fr_FR session'
  },
  'language': 'fr',
  'locale': 'FR'
}

Nvidia Shield

Pass language as a two-letter lowercase ISO 639-1 code and locale as a two-letter uppercase ISO 3166-1 country code.

Capability	Description	Value
`language`	Sets the device language	two-letter lowercase ISO 639-1 code. Example: `fr`, `de`, `en`, `es`, `hi`
`locale`	Sets the regional locale	2-letter uppercase ISO 3166-1 country code. Example: `FR`, `DE`, `US`, `GB`, `IN`

Example:

DesiredCapabilities capabilities = new DesiredCapabilities();
capabilities.setCapability("platformName", "Android");
capabilities.setCapability("app", "bs://<your_app_hashed_id>");

HashMap<String, Object> bstackOptions = new HashMap<>();
bstackOptions.put("deviceName", "Nvidia Shield TV Pro 2019");
bstackOptions.put("platformVersion", "11.0");
bstackOptions.put("projectName", "Smart TV Language Test");
bstackOptions.put("buildName", "Shield - German Locale");
bstackOptions.put("sessionName", "Shield de_DE session");
capabilities.setCapability("bstack:options", bstackOptions);

capabilities.setCapability("language", "de");
capabilities.setCapability("locale", "DE");

var capabilities = {
  'platformName': 'Android',
  'app': 'bs://<your_app_hashed_id>',
  'bstack:options': {
    'deviceName': 'Nvidia Shield TV Pro 2019',
    'platformVersion': '11.0',
    'projectName': 'Smart TV Language Test',
    'buildName': 'Shield - German Locale',
    'sessionName': 'Shield de_DE session'
  },
  'language': 'de',
  'locale': 'DE'
}

desired_caps = {
  'platformName' => 'Android',
  'app' => 'bs://<your_app_hashed_id>',
  'bstack:options' => {
    'deviceName' => 'Nvidia Shield TV Pro 2019',
    'platformVersion' => '11.0',
    'projectName' => 'Smart TV Language Test',
    'buildName' => 'Shield - German Locale',
    'sessionName' => 'Shield de_DE session'
  },
  'language' => 'de',
  'locale' => 'DE'
}

desired_caps = {
  'platformName': 'Android',
  'app': 'bs://<your_app_hashed_id>',
  'bstack:options': {
    'deviceName': 'Nvidia Shield TV Pro 2019',
    'platformVersion': '11.0',
    'projectName': 'Smart TV Language Test',
    'buildName': 'Shield - German Locale',
    'sessionName': 'Shield de_DE session'
  },
  'language': 'de',
  'locale': 'DE'
}

Apple TV (tvOS)

Pass both language and locale. Apple TV uses the underscored language_REGION format for locale (for example, fr_FR), which is different from the country-only format used on Android TV.

Capability	Description	Value
`language`	Sets the device language	two-letter lowercase language code. Example: `fr`, `de`, `en`, `es`
`locale`	Sets the regional locale	Underscored `language_REGION` format. Example: `fr_FR`, `de_DE`, `en_US`, `en_GB`

Example:

DesiredCapabilities capabilities = new DesiredCapabilities();
capabilities.setCapability("platformName", "tvos");
capabilities.setCapability("platformVersion", "17.0");
capabilities.setCapability("app", "bs://<your_app_hashed_id>");
capabilities.setCapability("automationName", "XCUITest");

HashMap<String, Object> bstackOptions = new HashMap<>();
bstackOptions.put("deviceName", "Apple TV 4K");
bstackOptions.put("projectName", "Smart TV Language Test");
bstackOptions.put("buildName", "AppleTV - French Locale");
bstackOptions.put("sessionName", "AppleTV fr_FR session");
capabilities.setCapability("bstack:options", bstackOptions);

capabilities.setCapability("language", "fr");
capabilities.setCapability("locale", "fr_FR");

var capabilities = {
  'platformName': 'tvos',
  'platformVersion': '17.0',
  'app': 'bs://<your_app_hashed_id>',
  'automationName': 'XCUITest',
  'bstack:options': {
    'deviceName': 'Apple TV 4K',
    'projectName': 'Smart TV Language Test',
    'buildName': 'AppleTV - French Locale',
    'sessionName': 'AppleTV fr_FR session'
  },
  'language': 'fr',
  'locale': 'fr_FR'
}

desired_caps = {
  'platformName' => 'tvos',
  'platformVersion' => '17.0',
  'app' => 'bs://<your_app_hashed_id>',
  'automationName' => 'XCUITest',
  'bstack:options' => {
    'deviceName' => 'Apple TV 4K',
    'projectName' => 'Smart TV Language Test',
    'buildName' => 'AppleTV - French Locale',
    'sessionName' => 'AppleTV fr_FR session'
  },
  'language' => 'fr',
  'locale' => 'fr_FR'
}

desired_caps = {
  'platformName': 'tvos',
  'platformVersion': '17.0',
  'app': 'bs://<your_app_hashed_id>',
  'automationName': 'XCUITest',
  'bstack:options': {
    'deviceName': 'Apple TV 4K',
    'projectName': 'Smart TV Language Test',
    'buildName': 'AppleTV - French Locale',
    'sessionName': 'AppleTV fr_FR session'
  },
  'language': 'fr',
  'locale': 'fr_FR'
}

Roku

Roku supports a limited set of 5 languages and does not support the locale capability. Passing locale on Roku will cause the session to fail.

Capability	Description	Value
`language`	Sets the device language	two-letter lowercase code. Supported values: `en`, `es`, `fr`, `pt`, `de`

Example:

DesiredCapabilities capabilities = new DesiredCapabilities();
capabilities.setCapability("platformName", "Roku");
capabilities.setCapability("appium:platform", "roku");
capabilities.setCapability("appium:automationName", "Roku");
capabilities.setCapability("appium:app", "bs://<your_app_hashed_id>");
capabilities.setCapability("appium:deviceName", "Roku Express 4K");
capabilities.setCapability("device", "Roku Express 4K");
capabilities.setCapability("os_version", "14.6");

HashMap<String, Object> bstackOptions = new HashMap<>();
bstackOptions.put("projectName", "Smart TV Language Test");
bstackOptions.put("buildName", "Roku - French Language");
bstackOptions.put("sessionName", "Roku fr session");
capabilities.setCapability("bstack:options", bstackOptions);

capabilities.setCapability("language", "fr");

var capabilities = {
  'platformName': 'Roku',
  'appium:platform': 'roku',
  'appium:automationName': 'Roku',
  'appium:app': 'bs://<your_app_hashed_id>',
  'appium:deviceName': 'Roku Express 4K',
  'device': 'Roku Express 4K',
  'os_version': '14.6',
  'bstack:options': {
    'projectName': 'Smart TV Language Test',
    'buildName': 'Roku - French Language',
    'sessionName': 'Roku fr session'
  },
  'language': 'fr'
}

desired_caps = {
  'platformName' => 'Roku',
  'appium:platform' => 'roku',
  'appium:automationName' => 'Roku',
  'appium:app' => 'bs://<your_app_hashed_id>',
  'appium:deviceName' => 'Roku Express 4K',
  'device' => 'Roku Express 4K',
  'os_version' => '14.6',
  'bstack:options' => {
    'projectName' => 'Smart TV Language Test',
    'buildName' => 'Roku - French Language',
    'sessionName' => 'Roku fr session'
  },
  'language' => 'fr'
}

desired_caps = {
  'platformName': 'Roku',
  'appium:platform': 'roku',
  'appium:automationName': 'Roku',
  'appium:app': 'bs://<your_app_hashed_id>',
  'appium:deviceName': 'Roku Express 4K',
  'device': 'Roku Express 4K',
  'os_version': '14.6',
  'bstack:options': {
    'projectName': 'Smart TV Language Test',
    'buildName': 'Roku - French Language',
    'sessionName': 'Roku fr session'
  },
  'language': 'fr'
}

Frequently asked questions

Does my session reset to the default language after the test?

Yes, BrowserStack restores the device language during cleanup, so the next session starts from a clean baseline.

Can I switch language mid-session?

No, the language is applied once at session start. To test a different language, start a new session with the updated language capability.

What happens if I pass an unsupported language?

For Amazon Fire TV, Nvidia Shield, and Apple TV, the session still starts but falls back to the device’s default language. Check your app’s UI to confirm whether the requested language took effect. For Roku, passing an unsupported language is rejected at session validation and the session fails to start. Only en, es, fr, pt, and de are accepted.

What if I pass locale on Roku?

Passing locale on Roku is rejected at session validation and the session fails to start. Roku does not expose a separate locale setting. Only language is accepted. Remove the locale key from your Roku capabilities entirely.

Why is the locale format different across platforms?

Each TV OS exposes its language settings differently:

Android TV (Fire TV, Nvidia Shield) follows the Android convention. Language and country are passed as separate values (language: fr, locale: FR).
Apple TV follows the tvOS convention. Locale uses the combined language_REGION format (locale: fr_FR).
Roku only exposes a single language setting with no locale at all.

Remote Control Navigation
Use IP Geolocation
If you have any queries, get in touch with us.

Did this page help you?

We're sorry to hear that. Please share your feedback so we can do better

Contact our Support team for immediate help while we work on improving our docs.

We're continuously improving our docs. We'd love to know what you liked

This page has exactly what I am looking for
This content & code samples are accurate and up-to-date
The content on this page is easy to understand
Other (please tell us more below)

Any additional feedback?

Thank you for your valuable feedback

Is this page helping you?

Yes

We're sorry to hear that. Please share your feedback so we can do better

Contact our Support team for immediate help while we work on improving our docs.

We're continuously improving our docs. We'd love to know what you liked

This page has exactly what I am looking for
This content & code samples are accurate and up-to-date
The content on this page is easy to understand
Other (please tell us more below)

Any additional feedback?

Thank you for your valuable feedback!

Set localization options for Smart TV tests

Amazon Fire TV

Nvidia Shield

Apple TV (tvOS)

Roku

Frequently asked questions

Does my session reset to the default language after the test?

Can I switch language mid-session?

What happens if I pass an unsupported language?

What if I pass locale on Roku?

Why is the locale format different across platforms?

Related topics

We're sorry to hear that. Please share your feedback so we can do better

We're continuously improving our docs. We'd love to know what you liked

We're sorry to hear that. Please share your feedback so we can do better

We're continuously improving our docs. We'd love to know what you liked