rtl_ui_guard 0.1.0

A lightweight Flutter toolkit for previewing, testing, and diagnosing Arabic, Kurdish Sorani, and other RTL user interfaces.

rtl_ui_guard

rtl_ui_guard is a lightweight Flutter toolkit for previewing and diagnosing right-to-left interfaces during development. It is designed for Arabic, Kurdish Sorani, and every locale that needs reliable RTL behavior.

The package stays independent of state-management and localization frameworks. Use it with Flutter localization, GetX, Riverpod, Bloc, or any other architecture.

Features

• Switch between LTR and RTL locales without restarting the application.
• Preview Arabic (ar), Kurdish Sorani (ckb), and English (en) out of the box.
• Simulate multiple accessibility text scales.
• Inspect a widget tree for clipped text.
• Detect translation-key-like strings accidentally rendered to users.
• Keep all tooling disabled in release builds by default.
• Integrate with an existing MaterialApp without taking ownership of navigation.

Installation

Add the package to pubspec.yaml:

dependencies:
  rtl_ui_guard: ^0.1.0

Quick start

Create and own the controller in the application shell. Rebuild MaterialApp from the controller so Flutter's localization delegates receive the selected locale.

class AppShell extends StatefulWidget {
  const AppShell({super.key});

  @override
  State<AppShell> createState() => _AppShellState();
}

class _AppShellState extends State<AppShell> {
  late final RtlUiGuardController controller;

  @override
  void initState() {
    super.initState();
    controller = RtlUiGuardController(
      supportedLocales: RtlGuardLocale.commonLocales,
    );
  }

  @override
  void dispose() {
    controller.dispose();
    super.dispose();
  }

  @override
  Widget build(BuildContext context) {
    return ListenableBuilder(
      listenable: controller,
      builder: (context, _) {
        return MaterialApp(
          locale: controller.locale,
          supportedLocales: controller.supportedLocales,
          builder: (context, child) {
            return RtlUiGuard(
              controller: controller,
              child: child ?? const SizedBox.shrink(),
            );
          },
          home: const DashboardPage(),
        );
      },
    );
  }
}

The floating guard panel is enabled only when kDebugMode is true. Override enabled when needed:

RtlUiGuard(
  controller: controller,
  enabled: false,
  child: child,
)

Diagnostics

Inspect a subtree after layout:

final report = RtlGuardDiagnostics.inspect(context);

for (final issue in report.issues) {
  debugPrint('${issue.type}: ${issue.message}');
}

Diagnostics currently report:

• textOverflow: a RenderParagraph exceeded its configured maximum lines.
• translationKey: visible text resembles an unresolved localization key such as dashboard.meetings.title.

Translation-key detection is intentionally conservative and can be disabled through RtlGuardDiagnostics.inspect.

Supported directionality

The direction resolver includes Arabic, Central Kurdish (ckb), Persian, Hebrew, Urdu, Pashto, Uyghur, and other commonly used RTL language codes. Applications may inject a custom resolver into RtlUiGuardController for domain-specific behavior.

Production safety

The overlay defaults to kDebugMode, so it is absent from release builds unless explicitly enabled. The diagnostics scanner runs only when called by the application.

Roadmap

• Golden-test scenario helpers.
• Screenshot matrices for locale and text-scale combinations.
• Optional checks for directional padding and directional icons.
• A DevTools-friendly diagnostics report.

License

MIT License. See LICENSE.