English	German	Arabic RTL	2x Scale

Why LocaleSweep? #

Your app looks perfect in English. Then a German user opens Settings and "Benachrichtigungseinstellungen" overflows the row. An Arabic user sees left-aligned text. A Japanese user hits an untranslated screen.

LocaleSweep catches these before your users do. It multiplies a single test across every combination of locale, text scale, viewport, and brightness — then captures a golden screenshot of each variant and fails only the ones that break.

sweepTest(
  'settings',
  builder: () => const MyApp(),
  locales: ['en', 'de', 'ar', 'ja'],
  textScales: [1.0, 2.0],
  viewports: [ViewportPreset.phone, ViewportPreset.tablet],
  darkMode: true,
  arbDir: 'lib/l10n',
);
// 4 locales x 2 scales x 2 viewports x 2 brightness = 32 test cases from one call

What it catches #

Getting started #

1. Install #

dev_dependencies:
  locale_sweep: ^0.6.0

2. Write a sweep test #

import 'package:flutter_test/flutter_test.dart';
import 'package:locale_sweep/locale_sweep.dart';

void main() {
  sweepTest(
    'onboarding',
    builder: () => const MyApp(),
    arbDir: 'lib/l10n',
  );
}

3. Run #

# Generate golden baselines (run locally first)
dart run locale_sweep update

# Compare against baselines (run in CI)
dart run locale_sweep run

run never regenerates goldens. update does. This prevents CI from silently accepting broken layouts.

Custom fonts #

By default, Flutter tests use the Ahem font (all squares). Pass setUp to load your app's fonts so screenshots look real:

sweepTest(
  'onboarding',
  builder: () => const MyApp(),
  setUp: () async {
    final font = rootBundle.load('assets/fonts/Roboto-Regular.ttf');
    final loader = FontLoader('Roboto')..addFont(font);
    await loader.load();
  },
);

Dark mode #

Enable darkMode: true to test every variant in both light and dark brightness:

sweepTest(
  'settings',
  builder: () => const SettingsPage(),
  darkMode: true,
  lightTheme: AppTheme.light,  // optional — defaults to ThemeData.light()
  darkTheme: AppTheme.dark,    // optional — defaults to ThemeData.dark()
);

Also configurable via YAML: dark_mode: true

Localizations integration #

Test individual screens with AppLocalizations.of(context) — no MaterialApp wrapper needed:

sweepTest(
  'settings',
  builder: () => const SettingsScreen(),  // just the screen, not the full app
  localizationsDelegates: AppLocalizations.localizationsDelegates,
  locales: ['en', 'de', 'ar', 'ja'],
  arbDir: 'lib/l10n',
);

LocaleSweep wraps the widget in a Localizations ancestor with your delegates, sets the locale per variant, and includes Material/Widgets fallback delegates automatically. Your screen's AppLocalizations.of(context) calls work as if it were inside a MaterialApp.

Base locale #

By default, ARB analysis compares against app_en.arb. For non-English base locales:

sweepTest(
  'settings',
  builder: () => const SettingsScreen(),
  baseLocale: 'de',  // compare other locales against German
);

Also configurable via YAML (base_locale: de) or env var (LOCALE_SWEEP_BASE_LOCALE=de).

Using with flutter gen-l10n #

Most Flutter apps use flutter gen-l10n to generate AppLocalizations. Here's how to wire it up:

Option 1: Full MaterialApp (tests the screen inside its normal app shell)

sweepTest(
  'home',
  builder: () => const MaterialApp(
    localizationsDelegates: AppLocalizations.localizationsDelegates,
    supportedLocales: AppLocalizations.supportedLocales,
    home: HomeScreen(),
  ),
  locales: ['en', 'de', 'ar', 'ja'],
  arbDir: 'lib/l10n',
);

Option 2: Screen in isolation (faster, tests just the screen with localizationsDelegates)

sweepTest(
  'settings',
  builder: () => const SettingsScreen(),
  localizationsDelegates: AppLocalizations.localizationsDelegates,
  locales: ['en', 'de', 'ar', 'ja'],
  arbDir: 'lib/l10n',
);

Option 2 skips the MaterialApp overhead and tests the screen directly. LocaleSweep injects the Localizations ancestor, so AppLocalizations.of(context)! works in both cases.

See the example app for a full gen-l10n setup with 8 locales and intentional bugs.

Using with slang #

slang uses a different file format than ARB, so the static analysis checks (missing keys, placeholders, untranslated strings) don't work against slang files directly. The runtime checks (overflow, RTL, dark mode, text scale, goldens) work out of the box since they're format-agnostic.

To get static analysis, use slang's built-in ARB export as a bridge:

# Export slang translations to ARB format
dart run slang:export --format arb --output lib/l10n/arb

Then point arbDir at the exported files:

sweepTest(
  'settings',
  builder: () => const SettingsScreen(),
  arbDir: 'lib/l10n/arb',  // slang's exported ARB files
);

This gives you the full static analysis (missing keys, placeholder mismatches, untranslated strings) on top of the runtime sweep. Re-export after updating translations to keep the checks in sync.

Screenshot diffing #

Set tolerance to allow minor pixel differences (anti-aliasing, CI rendering jitter) without masking real regressions:

sweepTest(
  'settings',
  builder: () => const SettingsPage(),
  tolerance: 0.5, // allow up to 0.5% pixel difference
);

Also configurable via YAML: tolerance: 0.5

When pixels differ, a 3-panel diff image (Golden | Actual | Diff) is saved to .locale_sweep/diffs/. Diff data flows into all report formats — percentage column in Markdown, badge + link in HTML, structured object in JSON.

Variant callbacks #

Run interactions after the widget is pumped. Use body for simple cases, variantBody when you need the current locale/brightness/direction:

sweepTest(
  'checkout',
  builder: () => const CheckoutPage(),
  body: (tester) async {
    await tester.tap(find.byType(ElevatedButton));
    await tester.pumpAndSettle();
  },
  // or: variantBody: (tester, variant) async { ... }
);

Skipping variants #

Exclude specific combinations from the matrix:

sweepTest(
  'settings',
  builder: () => const SettingsPage(),
  skip: (variant) {
    if (variant.locale == 'ja' && variant.textScale == 2.0) return true;
    if (variant.isDark && variant.viewport == ViewportPreset.tablet) return true;
    return false;
  },
);

Configuration #

YAML config #

Create locale_sweep.yaml for shared defaults:

locales: [en, de, ar, ja]
text_scales: [1.0, 2.0]
viewports:
  - { name: "375x667", width: 375, height: 667 }
  - { name: "768x1024", width: 768, height: 1024 }
dark_mode: true
tolerance: 0.5
arb_dir: lib/l10n
base_locale: en
screenshot_dir: .locale_sweep/screenshots
report_dir: .locale_sweep/reports

Any parameter passed directly to sweepTest() overrides the YAML config for that flow. Config validation warns about typos and type mismatches on stderr.

Environment variable overrides #

Override any config value in CI without modifying YAML:

LOCALE_SWEEP_LOCALES=en,de LOCALE_SWEEP_TOLERANCE=1.0 dart run locale_sweep run

Reports #

Three formats generated on every run:

• HTML — self-contained dashboard with filters, screenshot gallery, summary cards, dark/RTL badges
• Markdown — failure table with locale summary, ideal for PR comments
• JSON — machine-readable results for custom dashboards or trend tracking

Output structure #

.locale_sweep/
  reports/
    report.html
    report.md
    report.json
  screenshots/
    onboarding_en_393x852.png
    onboarding_en_dark_393x852.png
    onboarding_de_2.0x_393x852.png
    ...
  diffs/
    onboarding_de_393x852_diff.png
    ...
  runs/
    run_.../
      flutter.jsonl
      stderr.log
      results/
        flow_.../results.json

Each CLI invocation gets a separate run directory, so previous results cannot leak into the current report. Direct flutter test runs continue to write flow results under .locale_sweep/results/.

CI integration #

GitHub Actions #

- name: LocaleSweep
  run: dart run locale_sweep run --github-pr
  env:
    GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

--fail-on #

Control which categories trigger a non-zero exit code:

dart run locale_sweep run --fail-on overflow,golden   # only these categories fail
dart run locale_sweep run --fail-on none              # report-only mode
dart run locale_sweep run --fail-on all               # everything (default)

Categories: overflow, arb, golden, truncation, all, none

--fail-on none suppresses QA findings only. Compilation errors, broken test setup or callbacks, incomplete runs, and unreadable result files always return a non-zero exit code.

Parallel sharding #

Split large variant matrices across CI jobs for faster runs:

# GitHub Actions matrix strategy
strategy:
  matrix:
    shard: [0, 1, 2]
steps:
  - run: dart run locale_sweep run --shards 3 --shard-index ${{ matrix.shard }} -o shard_${{ matrix.shard }}
  - uses: actions/upload-artifact@v4
    with:
      name: shard-${{ matrix.shard }}
      path: shard_${{ matrix.shard }}/

# Merge step (needs: [test])
- uses: actions/download-artifact@v4
- run: dart run locale_sweep merge -i shard_0 -i shard_1 -i shard_2 --github-pr

The merge command combines shard reports into a single HTML/Markdown/JSON report and optionally posts to the PR.

Monorepo support #

Run sweep tests across multiple packages in a monorepo:

# Auto-discover packages with test/sweep/ directories
dart run locale_sweep scan

# Run sweep in specific packages
dart run locale_sweep run --packages apps/auth,apps/dashboard

# Combine with sharding
dart run locale_sweep run --packages apps/auth,apps/dashboard --shards 4 --shard-index 0

Auto-discovery checks for melos.yaml first, then scans for packages containing a test/sweep/ directory. Reports are generated per-package and merged into a single aggregate report.

CLI reference #

dart run locale_sweep run                                 # Compare goldens
dart run locale_sweep run --flows onboarding,checkout     # Specific flows
dart run locale_sweep run --github-pr                     # Post PR comment
dart run locale_sweep run --fail-on overflow,golden       # Selective failure
dart run locale_sweep run --config my_config.yaml         # Custom config
dart run locale_sweep run --verbose                       # Print flutter test output
dart run locale_sweep run --shards 3 --shard-index 0      # Parallel shard
dart run locale_sweep run --packages apps/a,apps/b        # Monorepo
dart run locale_sweep update                              # Regenerate baselines
dart run locale_sweep update --flows settings             # Update specific flows
dart run locale_sweep merge -i shard_0 -i shard_1         # Merge shard reports
dart run locale_sweep scan                                # Discover monorepo packages

API reference #

sweepTest() parameters #

ViewportPreset built-ins #

Custom: ViewportPreset(name: '1280x800', width: 1280, height: 800)

Real-world validation #

Zero noise on complete translations. Real findings on incomplete ones.

329 tests across 17 files. Full changelog. MIT License.