Visual testing across multiple locales

Structure your builds so that each language, country, or brand variant of a page has its own baseline.

When the same page is available in multiple locales, each variant can render differently while still representing the same test. Structuring these variants correctly helps App Percy maintain a separate baseline for each one.

When to use this guide

Use this guide when your test suite covers the same pages across multiple locales, countries, regions, or brands, and you see any of the following:

• Snapshots from one locale are compared against snapshots from another locale.
• A snapshot shows No baseline found even though the locale has run before.
• A comparison shows a diff ratio of 1.0, indicating that the images have no visual overlap.
• The same test passes in some runs and fails in others without any code changes.

These issues occur when locale variants are spread across builds or branches. App Percy then cannot resolve the correct baseline for each variant.

We recommend running all locales in a single build on a single branch. Give each locale its own snapshot name.

Use separate snapshot names for each locale

Run all locales in a single build on a single branch, and give each locale its own snapshot name.

For example, if a page is available in five languages, create five snapshots in the same build. Each snapshot name then maintains its own baseline history and approval state.

This works because App Percy tracks baselines by snapshot name. Giving each locale a unique snapshot name ensures that one locale is not compared against another.

Example

In this example, setAppLocale and navigateToCheckout are placeholders for your own helper methods.

This creates snapshots such as en-US_Checkout, fr-FR_Checkout, and de-DE_Checkout in the same build. Approving fr-FR_Checkout establishes the baseline for the French checkout page only.

Split locales by branch

If your development and deployment workflows are already separated by locale, you can use a separate branch for each locale. Configure App Percy with PERCY_BRANCH and PERCY_TARGET_BRANCH so that its branch structure follows your existing workflow.

This is an alternative to the recommended approach of using separate snapshot names. If all locales are managed on the same branch, use separate snapshot names instead. Creating separate branches only for App Percy adds maintenance without providing additional baseline separation.

For example, in a CI matrix that runs different locales and devices, set the environment variables for each lane:

Each lane runs as a separate build on its own branch and compares against the corresponding locale’s base branch.

For the complete list of supported variables, see Set environment variables.

Even when using a branch for each locale, include the device dimension in the snapshot name. The branch identifies the locale, and the snapshot name identifies every other dimension.

Name snapshots based on the variant dimensions

Build snapshot names using the dimensions that make each rendering different. A common naming pattern is:

<locale>_<page>_<device>

For example:

en-US_Checkout_iPhone14
en-US_Checkout_Pixel7
fr-FR_Checkout_iPhone14
fr-FR_Checkout_Pixel7

Keep the following points in mind:

• Keep snapshot names consistent across builds. App Percy uses the snapshot name to identify the baseline. Renaming fr-FR_Checkout to fr_FR_Checkout starts a new baseline history.
• Use a consistent order for dimensions. For example, always use locale, page, and then device. This makes related snapshots easier to identify in the dashboard.
• Generate names from variables. Build the snapshot name from the locale and other test variables instead of hard-coding values. This helps keep naming consistent as you add locales.
• A missing locale does not affect other locales. If a build does not include one locale, only that locale’s snapshot is missing. Other snapshots continue to compare against their respective baselines.

Run a subset of locales on a feature branch

If a feature branch changes only one locale, you can run that locale separately. Use partial builds to carry the remaining snapshots forward from the baseline.

This can help reduce snapshot consumption on branches where the other locales have not changed.

How A/B variants work with locale-based baselines

A/B testing allows a single snapshot name to have multiple approved baseline variants. A snapshot is automatically approved when it matches any of the approved variants.

Because variants work within a single snapshot name, they cannot provide separate baselines for multiple locales. Use a separate snapshot name for each locale. Within a locale, use A/B variants when that page has an intentional variation.

For example, if fr-FR_Checkout has two approved banner designs, you can maintain both as A/B variants under that snapshot name. These variants do not affect de-DE_Checkout or other locale snapshots.

Snapshots without a baseline

No baseline found means the snapshot does not have an approved baseline on the target branch.

Common causes include:

• The snapshot name changed between builds. Check the exact name, including casing and separators.
• This is the first build for a newly added locale. Review and approve the new snapshots to establish their baselines.
• The target branch does not have an approved build containing that snapshot name.

Add a locale to an existing project

Add the new locale to the existing test run. Its snapshots are then created in the same build as the other locales.

Do not run the new locale as a separate build on the same branch. Keeping all locale snapshots in one build maintains a complete set of approved snapshots on the baseline branch.

A new snapshot name has no baseline, so its first build has nothing to compare against. After the first build containing the new locale:

1. Review the new locale’s snapshots.
2. Approve the snapshots to establish their baselines.
3. Continue running the locale as part of the existing test suite.

Subsequent builds compare against those baselines. Existing locale baselines remain unchanged.

Locale-specific rendering differences

App Percy compares each snapshot against its baseline. It does not determine whether a rendering is correct in isolation.

This is particularly important when testing localized content, fonts, and scripts.

For example, App Percy cannot determine whether a glyph is rendered correctly when a snapshot has no baseline. A reviewer needs to verify the first rendering and approve it as the baseline.

Once the baseline is approved, App Percy can detect changes in subsequent builds, such as:

• A font falling back to a different font family.
• A glyph being substituted or rendered differently.
• Text layout changing because of a font or rendering change.
• Date, time, currency, or number formats changing between environments.
• Translated text expanding and shifting the page layout.

A person who can verify the rendering therefore needs to review and approve the first baseline.

Some rendering differences are expected. Exclude those regions from comparison if you do not want to review them on every build.

Ignore regions and baseline structuring address different problems. Fixing snapshot naming will not remove expected rendering differences, and adding ignore regions will not resolve an incorrect baseline structure.