locale_sweep 0.7.2

A CI quality gate for Flutter localization. Runs app flows across locales, device sizes, text scales, and RTL modes, then reports broken screens with screenshot proof.

0.7.2

• Pseudo-localization — add pseudo to locales to render the base locale with longer, accented, bracketed text (Settings → [Šéţţîñĝš one two]). Overflow and truncation detection then run against the expanded layout, so problems surface before translations exist. Works with any localization library because it rewrites the rendered text. SweepVariant gains isPseudo and renderLocale (the locale the app is rendered in); builderWithVariant users should pass variant.renderLocale.
• Hardcoded text detection — detectHardcodedText: true (or hardcoded_text: true in YAML) reports rendered text that matches no ARB message for the variant's locale, its language, or the base locale. Placeholders and plural / select branches are understood. Exempt brand names and user data with hardcodedTextAllowlist / hardcoded_text_allowlist. Findings are advisory, appear in all reports, and fail the run with the new --fail-on hardcoded category or --fail-on all.
• ArbAnalyzer.loadMessages — returns ARB message values per locale.

0.7.1

• Ignore intentional truncations — added ignoreTruncation to sweepTest plus TruncationIgnores helpers (byWidgetType, byKey, byMaxLines, byText, any, fromConfig) to exclude by-design text truncation from reports and --fail-on truncation. Declarative truncation_ignore: rules in locale_sweep.yaml cover the common list-row ellipsis case without any Dart code. TruncationDetector.detect gains an optional ignore parameter (backwards compatible).
• Safe YAML ignore rules — unknown keys, empty rules, wrong-typed values and invalid text_regex patterns print a warning once per flow and are skipped, so a typo can never hide every truncation.

Thanks to @AmisKwok for this contribution.

0.7.0

• Behavior change: truncation-only variants now report passed: true in report.json and count as passed in report summaries. CLI exit codes are unchanged — --fail-on all (the default) and --fail-on truncation still fail on truncations. Update custom tooling that reads passed from the JSON.
• Truncation detection no longer reports wrapping text — paragraphs without maxLines wrap instead of truncating, so the intrinsic-width fallback now only applies when maxLines is set. Single-line horizontal truncation (softWrap: false) is still detected.
• Truncations are advisory in pass/fail state — SweepResult.passed, SweepRunSummary.passed, JSON output, and report badges are driven by overflows, ARB issues and execution errors. Truncations are labelled ADVISORY; --fail-on truncation promotes them, and --fail-on all (the CLI default) already includes them.
• untranslated_allowlist config — exempt intentionally identical values (app names, language self-names) from the ARB untranslated check. Missing keys and placeholder mismatches are still reported.
• builderWithVariant — sweepTest can now pass the current SweepVariant to its builder, so callers can supply the variant locale directly instead of relying on an injected Localizations ancestor. Exactly one of builder or builderWithVariant is required.
• Report screenshots resolve locally — results now record the actual package-relative screenshot location (resolved through the golden comparator's basedir; absolute configured paths stay absolute), and report links are rewritten relative to the report output directory.
• Capture-only screenshots — new compareScreenshots parameter (default true). Set it to false with captureScreenshots: true to write PNGs for reports without asserting against golden baselines.

Thanks to @jeromexiong for the contributions in this release.

0.6.2

• Fix crash on the flutter test --machine startup line — the CLI parsed every stdout line as a JSON object, but flutter test --machine first prints a JSON array line ([{"event":"test.startedProcess","params":{...}}]). The resulting TypeError was not caught by the on FormatException handler, so run and update aborted with an unhandled exception before writing any results or report. Both shapes are now decoded by one shared helper (parseMachineLine in lib/src/cli/machine_output.dart) that returns the event objects a line carries and ignores anything else. No public API change.
• --flows matches flow names — --flows login now selects sweepTest('login', ...) in any test file and runs only that flow, instead of requiring a file named login_test.dart. File-name matching still works. When nothing matches, the error lists the available flows.

0.6.1

• Truncation findings no longer fail direct tests — truncation issues are now advisory in flutter test runs. They are recorded in SweepResult for the CLI's --fail-on truncation to handle, preventing unexpected test failures in existing suites after upgrading to 0.6.0.

0.6.0

• Text truncation detection — after every pumpAndSettle(), walks the render tree to find RenderParagraph nodes where text is silently truncated by ellipsis, clip, or fade overflow modes. Reports the text, locale, overflow mode, available vs. desired width, and maxLines. Catches localization bugs that overflow detection misses — translated strings that fit the container but lose content.
• --fail-on truncation — new category for the --fail-on flag. Truncation findings are included in Markdown, HTML, and JSON reports alongside overflows and ARB issues.
• Report improvements — Markdown and HTML locale summary tables include a Truncations column. HTML report adds a Truncations summary card. CLI summary line includes truncation count.
• Backwards compatible — truncations field defaults to empty; existing JSON results without it deserialize cleanly.

0.5.1

• Reliable exit codes — ARB-only findings now mark variants as failed and respect --fail-on; unexpected test, setup, compilation, and result-read failures always return a non-zero exit, even with --fail-on none.
• Consistent reports — Markdown, HTML, JSON, CLI summaries, and process exit codes now derive pass/fail state from the same result model. Reports also expose execution errors when a run is incomplete.
• Current-run isolation — every CLI invocation writes to a unique results directory, so stale files cannot contaminate a later report. Duplicate flow names across test isolates are preserved, and corrupt or partial results fail visibly.
• Configuration propagation — sweepTest() now loads the CLI-selected YAML file and environment overrides automatically. Explicit Dart arguments remain highest priority, including screenshotDir.
• Safer CLI orchestration — single-package, monorepo, shard, merge, and golden-update paths share the same validation and failure rules. Invalid categories, shard ranges, configs, flow selections, and missing packages fail clearly.
• 329 tests total across 17 test files.

0.5.0

• Localizations integration — new localizationsDelegates parameter on sweepTest(). Wraps the widget in a Localizations ancestor so AppLocalizations.of(context) works for individual screen tests without needing a full MaterialApp. Fallback Material/Widgets delegates are included automatically for all locales.
• baseLocale config — configurable base locale for ARB analysis. Set via sweepTest(baseLocale:), YAML base_locale:, or LOCALE_SWEEP_BASE_LOCALE env var. Defaults to 'en'.
• parseLocale() helper — proper BCP-47 locale parsing. Handles en, en_US, pt-BR, zh_Hans, zh_Hans_CN. Used internally and exported for user convenience.
• Example app uses flutter gen-l10n — all three example screens now use AppLocalizations.of(context) instead of hardcoded strings. Demonstrates both patterns: full MaterialApp with delegates (home) and screen-in-isolation with localizationsDelegates param (settings, profile).
• 320 tests total across 16 test files.

0.4.2

• German umlaut fix — screenshot gallery now renders proper umlauts (Übersetzungen, Prüfungen, Schlüssel, etc.) instead of ASCII fallbacks.
• Japanese translations — gallery screenshots use real Japanese text instead of untranslated English strings. Added NotoSansJP font for CJK rendering.
• Version badge — gallery screenshots updated from v0.1.1 to v0.4.1.

0.4.1

• Example app — 3 sweep tests across 8 locales (en, de, ar, ja, ko, he, th, hi) with intentional bugs: missing ARB keys, placeholder mismatches, untranslated strings, overflow layouts, RTL issues.
• Arabic RTL screenshot — README gallery now shows real Arabic text with mirrored layout instead of Config screen. Added NotoNaskhArabic font for proper rendering.
• pub.dev Example tab — updated example.dart with 64-variant sweep (8 locales × 2 scales × 2 viewports × 2 brightness).

0.4.0

• Parallel sharding — --shards N --shard-index I CLI flags split variant matrices across CI jobs. Passes through to flutter test --total-shards/--shard-index.
• Merge command — locale_sweep merge -i shard_0 -i shard_1 combines shard reports into a single HTML/Markdown/JSON report. Supports --github-pr and --fail-on.
• Monorepo support — locale_sweep scan auto-discovers packages with test/sweep/ dirs (checks melos.yaml first). --packages apps/auth,apps/dashboard runs sweep across multiple packages with merged reporting.
• Landscape presets — 4 new presets: phoneSmallLandscape (667x375), phoneLandscape (852x393), phoneWideLandscape (915x412), tabletLandscape (1024x768).
• CLI progress — real-time pass/fail counts during flutter test runs.
• Environment overrides — LOCALE_SWEEP_LOCALES, LOCALE_SWEEP_TOLERANCE, etc. for CI without modifying YAML.
• setUp callback — sweepTest(setUp: () async { ... }) for loading custom fonts before the sweep group.
• CLI parser extracted — testable cli_parser.dart library with 43 new tests.
• Bug fix — ARB analyzer false positives on ICU plural/select syntax ({count, plural, ...}).
• Bug fix — CLI crash from transitive dart:ui dependency. Extracted DiffResult and OverflowError into pure-Dart files.
• Bug fix — removed http package dependency. GitHubReporter uses dart:io HttpClient directly.
• 283 tests total across 14 test files.

0.3.0

• Screenshot diffing — pixel-level diff via GoldenDiffer.computeDiff(). Per-channel threshold of 2 absorbs anti-aliasing jitter.
• Tolerance — tolerance parameter on sweepTest() and in locale_sweep.yaml. Screenshots within tolerance pass even when pixels differ.
• Diff images — 3-panel side-by-side (Golden | Actual | Diff) saved to .locale_sweep/diffs/. Changed pixels highlighted in magenta.
• Diff in reports — Diff % column in Markdown, diff badge + link in HTML, structured object in JSON.
• DiffResult model — diffPercent, changedPixels, totalPixels, diffImagePath with full JSON serialization.
• Config — tolerance key in YAML, tolerance and diffOutputDir params on sweepTest().
• 202 tests total across 11 test files.

0.2.0

• Dark mode — darkMode: true on sweepTest() tests every variant in both light and dark brightness. Optional lightTheme/darkTheme params.
• Variant exclusion — skip callback to exclude specific locale/scale/viewport/brightness combos.
• HTML report — self-contained dashboard with dark theme, summary cards, screenshot gallery, interactive filters, locale summary table.
• --fail-on — CLI flag for selective failure categories (overflow, arb, golden, all, none).
• Config validation — warns on unknown keys (typos) and type mismatches. Falls back to defaults.
• File-based results — each flow writes JSON to .locale_sweep/results/. Isolate-safe, no global state.
• 167 tests total.

0.1.7

• Updated README with variantBody examples, SweepVariant API docs, untranslated detection docs.

0.1.6

• Auto-published on 2026-09-03.

0.1.5

• Expanded RTL locale detection: 10 locales (ar, he, fa, ur, ku, ps, yi, dv, sd, ug) with subtag support (e.g. ar_EG).
• CLI now reads locale_sweep.yaml config file via --config flag.
• CLI uses GitHubReporter for PR comments instead of duplicate HTTP logic.
• Added variantBody callback to sweepTest() for locale-aware test interactions.
• Added ArbIssueType.untranslated detection for strings identical to the base locale.

0.1.4

• Fixed Dart SDK constraint from ^3.11.5 to ^3.8.0 for broader compatibility.
• Centered title and badges on pub.dev README.
• Updated CI workflows to Flutter 3.41.9.

0.1.3

• Rewrote README for pub.dev compatibility — pure Markdown, proper image alignment.
• Added CI and auto-publish GitHub Actions workflows.

0.1.2

• Updated README with professional layout and screenshot gallery.
• Fixed GitHub repository URLs in pubspec.yaml.

0.1.1

• Add dartdoc comments to all public API elements.
• Add example/example.dart for pub.dev example tab.
• Real-world validation: tested against Spotube (48k stars) and wger (960 stars).

0.1.0

• Initial release.
• sweepTest() generates locales × textScales × viewports test matrix.
• OverflowDetector captures RenderFlex overflow with pixel counts.
• ArbAnalyzer detects missing ARB keys and placeholder mismatches.
• Golden screenshot comparison (run vs update commands).
• Markdown and JSON report generation.
• GitHub PR comment integration.
• Built-in viewport presets: phone, phoneSmall, phoneWide, tablet.
• RTL auto-detection for Arabic, Hebrew, and Farsi.