Sway #

Type-safe localization for Flutter apps - write nested translations, get strongly typed Dart, and switch languages (including RTL) in your app.

Why Sway? #

Install #

dart pub add sway

60-second quickstart (full Sway format) #

1. Create lib/i18n/en.sway.json:

{
  "home": {
    "welcome": "Welcome, {name}!",
    "itemCount": {
      "one": "{count} item",
      "other": "{count} items"
    }
  }
}

2. Generate

dart run sway:codegen

Creates sway.g.dart + sway_en.g.dart (and more locales as you add them).

3. Wire the app

import 'package:flutter/material.dart';
import 'package:sway/sway.dart';
import 'i18n/sway.g.dart';

class MyApp extends StatefulWidget {
  const MyApp({super.key});
  @override
  State<MyApp> createState() => _MyAppState();
}

class _MyAppState extends State<MyApp> {
  Locale _locale = const Locale('en');
  late final adapter = SwayFormatAdapter(
    supportedLocales: SwayTranslations.supportedLocales,
    currentLocale: _locale,
    onLocaleChange: (l) => setState(() => _locale = l),
  );

  @override
  Widget build(BuildContext context) {
    final translations = SwayTranslations.forLocale(_locale);
    return MaterialApp(
      locale: _locale,
      supportedLocales: SwayTranslations.supportedLocales,
      home: SwayScope(
        translations: translations,
        child: SwayOverlay(
          adapter: adapter,
          child: const HomePage(),
        ),
      ),
    );
  }
}

class HomePage extends StatelessWidget {
  const HomePage({super.key});
  @override
  Widget build(BuildContext context) {
    final t = context.t; // shorthand
    return Text(t.home.welcome(name: 'Dipesh'));
  }
}

API cheatsheet #

Nested keys match your JSON (profile.editProfile → t.profile.editProfile) so sections with the same leaf name (title) never collide.

Optional config - lib/i18n/sway.config.json #

{
  "baseLocale": "en",
  "localeDir": "lib/i18n",
  "outputFile": "lib/i18n/sway.g.dart",
  "fallbackStrategy": "baseLocale"
}

Overlay only (keep ARB / gen-l10n) #

You do not need Sway JSON. For production shells (MaterialApp.builder + GetIt / Provider), use the one-liner:

builder: (context, child) => Sway.debugOverlay(
  localeListenable: localeService, // ChangeNotifier / Listenable
  getLocale: () => localeService.locale,
  setLocale: localeService.setLocale,
  supportedLocales: AppLocalizations.supportedLocales,
  debugOnly: true,
  child: child!,
),

Long-press the bubble to hide it (hot reload / restart brings it back).

Minimal StatefulWidget + home: tutorial and more recipes: doc/OVERLAY_ONLY.md

Migration #

# Always dry-run first
dart run sway:migrate --from arb --input lib/l10n --output lib/i18n --dry-run
dart run sway:migrate --from arb --input lib/l10n --output lib/i18n

dart run sway:migrate --from easy_localization --input assets/translations --output lib/i18n
dart run sway:migrate --from slang --input lib/i18n --output lib/i18n_migrated

Full guide: doc/MIGRATION.md

vs Flutter official (ARB + gen-l10n) #

Step-by-step: doc/INTEGRATION.md

Commands #

dart run sway:codegen
dart run sway:migrate --from arb --input lib/l10n --output lib/i18n
flutter test

Example #

cd example
flutter run

Six locales (en, ar, es, de, ja, he), plurals, RTL, and the overlay.

Troubleshooting #

License #

MIT - see LICENSE.

© Darkmintis