Test in different locales

Test your app in multiple languages and regions using locale configuration.

Testing how your app handles different languages and regional formats is critical for a global user base. In Maestro, the locale is a global device setting. Because changing the system language requires a device-level configuration change, it is handled via the CLI only at runtime.

To define the locale, provide the --device-locale flag at execution time using the Maestro CLI. For automated workflows, you can use CI wrappers to configure the locale for Maestro Cloud runs.

Note that there is no place within a Flow itself (such as launchApp or config.yaml) to define the locale.

Web support

Maestro can change the locale for Android and iOS devices, but it does not control the internal language settings of the Chrome browser used for Web tests.

Set the locale

To run a Flow in a specific language, use the --device-locale flag when executing commands from the terminal. The value passed to --device-locale must be a combination of an ISO-639-1 language code and an ISO-3166-1 country code, separated by an underscore (_).

You can use --device-locale with the maestro start-device and maestro cloud commands. It is not possible to define the locale when running the maestro test command.

Refer to Locales supported by Maestro for the full list of supported locales.

The following examples show how to start devices with specific locales.

Android

# Create a new Android emulator with the locale set to France (French)
maestro start-device \
  --platform android \
  --device-locale fr_FR

iOS

What happens to the device?

When you start a device and define a locale, Maestro attempts to change the system language and region of the connected simulator or emulator before running any Flow.

After starting the device with the desired locale, you can run your tests normally. Maestro continues using the locale defined during device initialization.

maestro test your_flow.yaml

Combine locales and tags

If certain tests should only run in specific languages (for example, tests that validate French translations), a recommended approach is to combine --device-locale with tags. This ensures that only tests relevant to the selected locale are executed, making test runs faster and more efficient.

First, define a tag in the Flow. In the following example, the french tag indicates that the Flow is intended to validate the app using the French translation.

# flows/login_fr.yaml
appId: com.example.app
tags:
  - french
---
- launchApp
- assertVisible: "Bienvenue"

After tagging your Flows, specify the tag when running tests using the --include-tags flag.

# Start the Android device using the French locale
maestro start-device --platform android --device-locale fr_FR
# Run only tests tagged as French
maestro test --include-tags french .maestro/

Related Documentation

• Locales supported by Maestro: Check the full list of supported locales.

• Maestro CLI overview: Learn how to execute flows using the CLI.

• Test discovery and tags: Learn how to group and filter your localization tests.