MaterialApp
  └── Localizations widget
        └── LocalizationsDelegate<T>     (one per localizable resource class)
              └── Generated AppLocalizations   (type-safe accessors for your strings)

dependencies:
  flutter:
    sdk: flutter
  flutter_localizations:
    sdk: flutter
  intl: any  # version managed by the SDK

flutter:
  generate: true  # enables synthetic package for gen-l10n output

arb-dir: lib/l10n
template-arb-file: app_en.arb
output-localization-file: app_localizations.dart
output-class: AppLocalizations
nullable-getter: false          # AppLocalizations.of(context) returns non-nullable
synthetic-package: true         # output to .dart_tool (default, no manual import path needed)

lib/l10n/
├── app_en.arb      (template — must contain all keys + metadata)
├── app_zh.arb
├── app_es.arb
└── app_ar.arb

{
  "@@locale": "en",
  "appTitle": "My Shop",
  "@appTitle": {
    "description": "The title shown in the app bar on the home page"
  },
  "itemCount": "{count, plural, =0{No items} =1{1 item} other{{count} items}}",
  "@itemCount": {
    "description": "Label showing how many items are in the cart",
    "placeholders": {
      "count": {
        "type": "int"
      }
    }
  }
}

flutter gen-l10n

import 'package:flutter_gen/gen_l10n/app_localizations.dart';

class MyApp extends StatelessWidget {
  @override
  Widget build(BuildContext context) {
    return MaterialApp(
      localizationsDelegates: AppLocalizations.localizationsDelegates,
      supportedLocales: AppLocalizations.supportedLocales,
      home: const HomePage(),
    );
  }
}

class HomePage extends StatelessWidget {
  const HomePage();

  @override
  Widget build(BuildContext context) {
    final l10n = AppLocalizations.of(context);
    return Scaffold(
      appBar: AppBar(title: Text(l10n.appTitle)),
      body: Center(child: Text(l10n.itemCount(3))),
    );
  }
}

{
  "greeting": "Hello!",
  "@greeting": {
    "description": "Simple greeting shown on launch"
  }
}

{
  "welcome": "Welcome, {userName}!",
  "@welcome": {
    "description": "Greeting with the user's name",
    "placeholders": {
      "userName": {
        "type": "String",
        "example": "Alice"
      }
    }
  }
}

{
  "inboxMessages": "{count, plural, =0{No messages} =1{1 message} other{{count} messages}}",
  "@inboxMessages": {
    "description": "Inbox badge count",
    "placeholders": {
      "count": {
        "type": "int"
      }
    }
  }
}

{
  "inboxMessages": "{count, plural, =0{لا رسائل} =1{رسالة واحدة} =2{رسالتان} few{{count} رسائل} many{{count} رسالة} other{{count} رسالة}}"
}

{
  "profileHeader": "{gender, select, male{His profile} female{Her profile} other{Their profile}}",
  "@profileHeader": {
    "description": "Profile page heading, gendered",
    "placeholders": {
      "gender": {
        "type": "String"
      }
    }
  }
}

{
  "orderStatus": "{status, select, pending{Order pending} shipped{Order shipped} delivered{Order delivered} other{Unknown status}}",
  "@orderStatus": {
    "description": "Human-readable order status label",
    "placeholders": {
      "status": {
        "type": "String"
      }
    }
  }
}

{
  "salesReport": "Revenue: {revenue} on {reportDate}. Growth: {growthRate}",
  "@salesReport": {
    "description": "Sales dashboard summary line",
    "placeholders": {
      "revenue": {
        "type": "double",
        "format": "compactCurrency",
        "optionalParameters": {
          "decimalDigits": 2,
          "symbol": "$"
        }
      },
      "reportDate": {
        "type": "DateTime",
        "format": "yMMMd"
      },
      "growthRate": {
        "type": "double",
        "format": "percentPattern"
      }
    }
  }
}

{
  "@@locale": "en",

  "appTitle": "My Shop",
  "@appTitle": {
    "description": "Application title in the app bar"
  },

  "welcome": "Welcome, {userName}!",
  "@welcome": {
    "description": "Personalized greeting",
    "placeholders": {
      "userName": { "type": "String", "example": "Alice" }
    }
  },

  "cartItemCount": "{count, plural, =0{Your cart is empty} =1{1 item in your cart} other{{count} items in your cart}}",
  "@cartItemCount": {
    "description": "Cart item count badge",
    "placeholders": {
      "count": { "type": "int" }
    }
  },

  "lastLogin": "Last login: {date}",
  "@lastLogin": {
    "description": "Shows when the user last logged in",
    "placeholders": {
      "date": { "type": "DateTime", "format": "yMMMd" }
    }
  },

  "totalPrice": "Total: {price}",
  "@totalPrice": {
    "description": "Cart total price",
    "placeholders": {
      "price": {
        "type": "double",
        "format": "compactCurrency",
        "optionalParameters": { "symbol": "$" }
      }
    }
  },

  "orderShippedBy": "{gender, select, male{He shipped your order} female{She shipped your order} other{They shipped your order}}",
  "@orderShippedBy": {
    "description": "Shipping confirmation with gendered pronoun",
    "placeholders": {
      "gender": { "type": "String" }
    }
  }
}

import 'package:flutter/material.dart';
import 'package:shared_preferences/shared_preferences.dart';

class LocaleNotifier extends ChangeNotifier {
  static const _prefKey = 'app_locale';

  Locale _locale;
  Locale get locale => _locale;

  LocaleNotifier(Locale initial) : _locale = initial;

  /// Load persisted locale, falling back to platform default.
  static Future<LocaleNotifier> create() async {
    final prefs = await SharedPreferences.getInstance();
    final tag = prefs.getString(_prefKey);
    final locale = tag != null ? Locale(tag) : WidgetsBinding.instance.platformDispatcher.locale;
    return LocaleNotifier(locale);
  }

  Future<void> setLocale(Locale newLocale) async {
    if (_locale == newLocale) return;
    _locale = newLocale;
    notifyListeners();
    final prefs = await SharedPreferences.getInstance();
    await prefs.setString(_prefKey, newLocale.languageCode);
  }
}

import 'package:provider/provider.dart';
import 'package:flutter_gen/gen_l10n/app_localizations.dart';

Future<void> main() async {
  WidgetsFlutterBinding.ensureInitialized();
  final localeNotifier = await LocaleNotifier.create();
  runApp(
    ChangeNotifierProvider.value(
      value: localeNotifier,
      child: const MyApp(),
    ),
  );
}

class MyApp extends StatelessWidget {
  const MyApp();

  @override
  Widget build(BuildContext context) {
    final locale = context.watch<LocaleNotifier>().locale;
    return MaterialApp(
      locale: locale,
      localizationsDelegates: AppLocalizations.localizationsDelegates,
      supportedLocales: AppLocalizations.supportedLocales,
      home: const HomePage(),
    );
  }
}

class LocalePicker extends StatelessWidget {
  const LocalePicker();

  @override
  Widget build(BuildContext context) {
    final notifier = context.read<LocaleNotifier>();
    return DropdownButton<Locale>(
      value: context.watch<LocaleNotifier>().locale,
      items: AppLocalizations.supportedLocales.map((locale) {
        return DropdownMenuItem(
          value: locale,
          child: Text(_labelFor(locale)),
        );
      }).toList(),
      onChanged: (locale) {
        if (locale != null) notifier.setLocale(locale);
      },
    );
  }

  String _labelFor(Locale locale) {
    switch (locale.languageCode) {
      case 'en': return 'English';
      case 'zh': return 'Chinese';
      case 'es': return 'Spanish';
      case 'ar': return 'Arabic';
      default:   return locale.languageCode;
    }
  }
}

import 'package:flutter_riverpod/flutter_riverpod.dart';
import 'package:shared_preferences/shared_preferences.dart';

final localeProvider = AsyncNotifierProvider<LocaleNotifier, Locale>(LocaleNotifier.new);

class LocaleNotifier extends AsyncNotifier<Locale> {
  static const _prefKey = 'app_locale';

  @override
  Future<Locale> build() async {
    final prefs = await SharedPreferences.getInstance();
    final tag = prefs.getString(_prefKey);
    return tag != null ? Locale(tag) : const Locale('en');
  }

  Future<void> setLocale(Locale newLocale) async {
    state = AsyncData(newLocale);
    final prefs = await SharedPreferences.getInstance();
    await prefs.setString(_prefKey, newLocale.languageCode);
  }
}

Directionality(
  textDirection: TextDirection.rtl,
  child: MyWidget(),
)

// WRONG: does not flip in RTL
const EdgeInsets.only(left: 16)

// CORRECT: flips start/end based on text direction
const EdgeInsetsDirectional.only(start: 16)

// WRONG: arrow always points left, even in RTL
Icon(Icons.arrow_back)

// CORRECT: arrow_back_ios flips automatically with Directionality,
// but only if you use it through a widget that respects Directionality.
// Safest approach: use the dedicated directional variants
Icon(Icons.arrow_back)  // Does NOT auto-flip
Icon(Icons.arrow_forward)  // Does NOT auto-flip

// Use the BackButton widget instead — it handles direction automatically
const BackButton()

class OrderCard extends StatelessWidget {
  final String title;
  final String price;
  final String timeAgo;

  const OrderCard({
    required this.title,
    required this.price,
    required this.timeAgo,
  });

  @override
  Widget build(BuildContext context) {
    return Card(
      // Use EdgeInsetsDirectional, not EdgeInsets
      margin: const EdgeInsetsDirectional.only(start: 16, end: 16, bottom: 8),
      child: Padding(
        padding: const EdgeInsetsDirectional.all(12),
        child: Row(
          children: [
            // Leading icon — Row handles ordering in RTL automatically
            const Icon(Icons.receipt_long),
            const SizedBox(width: 12),
            Expanded(
              child: Column(
                // CrossAxisAlignment.start is direction-aware
                crossAxisAlignment: CrossAxisAlignment.start,
                children: [
                  Text(title, style: Theme.of(context).textTheme.titleMedium),
                  Text(timeAgo, style: Theme.of(context).textTheme.bodySmall),
                ],
              ),
            ),
            Text(price, style: Theme.of(context).textTheme.titleMedium),
          ],
        ),
      ),
    );
  }
}

testWidgets('OrderCard renders correctly in RTL', (tester) async {
  await tester.pumpWidget(
    const Directionality(
      textDirection: TextDirection.rtl,
      child: MaterialApp(
        home: Scaffold(
          body: OrderCard(
            title: 'Test Order',
            price: '\$42.00',
            timeAgo: '2h ago',
          ),
        ),
      ),
    ),
  );

  // Verify the price appears to the left of the title in RTL
  final titleOffset = tester.getTopLeft(find.text('Test Order'));
  final priceOffset = tester.getTopLeft(find.text('\$42.00'));
  expect(priceOffset.dx, lessThan(titleOffset.dx));
});

import 'package:intl/intl.dart';

// Decimal grouping: locale-dependent separators
NumberFormat.decimalPattern('en_US').format(1234567.89);  // "1,234,567.89"
NumberFormat.decimalPattern('de_DE').format(1234567.89);  // "1.234.567,89"

// Currency
NumberFormat.currency(locale: 'en_US', symbol: '\$').format(1234.5);  // "\$1,234.50"
NumberFormat.currency(locale: 'ja_JP', symbol: '¥').format(1234);  // "¥1,234"

// Compact
NumberFormat.compact(locale: 'en').format(1200000);  // "1.2M"
NumberFormat.compact(locale: 'zh').format(1200000);  // "120万"

// Percent
NumberFormat.percentPattern('en').format(0.127);  // "13%"

import 'package:intl/intl.dart';

final now = DateTime(2025, 3, 15, 14, 30);

DateFormat.yMMMd('en_US').format(now);     // "Mar 15, 2025"
DateFormat.yMMMd('zh_CN').format(now);     // "2025年3月15日"
DateFormat.yMMMd('de_DE').format(now);     // "15. Mär. 2025"

DateFormat.jms('en_US').format(now);       // "2:30:00 PM"
DateFormat.jms('de_DE').format(now);       // "14:30:00"

DateFormat.EEEE('en').format(now);         // "Saturday"
DateFormat.EEEE('ar').format(now);         // "السبت"

class AppFormatters {
  final String locale;

  AppFormatters(this.locale);

  /// Creates an instance from the current BuildContext locale.
  factory AppFormatters.of(BuildContext context) {
    return AppFormatters(Localizations.localeOf(context).toString());
  }

  String decimal(num value) => NumberFormat.decimalPattern(locale).format(value);

  String currency(double value, {String symbol = '\$'}) =>
      NumberFormat.currency(locale: locale, symbol: symbol).format(value);

  String compact(num value) => NumberFormat.compact(locale: locale).format(value);

  String percent(double value) => NumberFormat.percentPattern(locale).format(value);

  String dateShort(DateTime dt) => DateFormat.yMd(locale).format(dt);

  String dateMedium(DateTime dt) => DateFormat.yMMMd(locale).format(dt);

  String dateLong(DateTime dt) => DateFormat.yMMMMEEEEd(locale).format(dt);

  String time(DateTime dt) => DateFormat.jms(locale).format(dt);

  /// Relative time ("2 hours ago", "just now").
  String relativeTime(DateTime dt) {
    final diff = DateTime.now().difference(dt);
    if (diff.inSeconds < 60) return 'just now';
    if (diff.inMinutes < 60) return '${diff.inMinutes}m ago';
    if (diff.inHours < 24) return '${diff.inHours}h ago';
    if (diff.inDays < 7) return '${diff.inDays}d ago';
    return dateMedium(dt);
  }
}

class PriceBanner extends StatelessWidget {
  final double price;
  final DateTime lastUpdated;

  const PriceBanner({required this.price, required this.lastUpdated});

  @override
  Widget build(BuildContext context) {
    final fmt = AppFormatters.of(context);
    return Column(
      crossAxisAlignment: CrossAxisAlignment.start,
      children: [
        Text(fmt.currency(price), style: Theme.of(context).textTheme.headlineMedium),
        Text('Updated: ${fmt.dateMedium(lastUpdated)}'),
      ],
    );
  }
}

{
  "checkoutButton": "Checkout ({count})",
  "@checkoutButton": {
    "description": "Label on the checkout button in the cart. The count is the number of items being purchased.",
    "placeholders": {
      "count": {
        "type": "int",
        "example": "3"
      }
    }
  }
}

# .github/workflows/l10n.yml (simplified)
name: Sync translations
on:
  push:
    paths:
      - 'lib/l10n/app_en.arb'

jobs:
  upload:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Upload source to Crowdin
        uses: crowdin/github-action@v2
        with:
          upload_sources: true
          upload_translations: false
          crowdin_branch_name: ${{ github.ref_name }}
        env:
          CROWDIN_PROJECT_ID: ${{ secrets.CROWDIN_PROJECT_ID }}
          CROWDIN_PERSONAL_TOKEN: ${{ secrets.CROWDIN_TOKEN }}

# l10n.yaml
untranslated-messages-file: l10n_untranslated.txt   # writes missing keys to a file

#!/bin/bash
# ci/check_translations.sh
if [ -s l10n_untranslated.txt ]; then
  echo "ERROR: Untranslated keys found:"
  cat l10n_untranslated.txt
  exit 1
fi

import 'package:flutter_test/flutter_test.dart';
import 'package:flutter_gen/gen_l10n/app_localizations.dart';

Widget buildTestableWidget(Widget child, {Locale locale = const Locale('en')}) {
  return MaterialApp(
    locale: locale,
    localizationsDelegates: AppLocalizations.localizationsDelegates,
    supportedLocales: AppLocalizations.supportedLocales,
    home: child,
  );
}

testWidgets('home page shows localized title in Spanish', (tester) async {
  await tester.pumpWidget(
    buildTestableWidget(const HomePage(), locale: const Locale('es')),
  );
  await tester.pumpAndSettle();  // wait for async delegate loading

  expect(find.text('Mi Tienda'), findsOneWidget);
});

testWidgets('checkout button golden - English', (tester) async {
  await tester.pumpWidget(
    buildTestableWidget(const CheckoutButton(itemCount: 3)),
  );
  await tester.pumpAndSettle();
  await expectLater(
    find.byType(CheckoutButton),
    matchesGoldenFile('goldens/checkout_button_en.png'),
  );
});

testWidgets('checkout button golden - German', (tester) async {
  await tester.pumpWidget(
    buildTestableWidget(
      const CheckoutButton(itemCount: 3),
      locale: const Locale('de'),
    ),
  );
  await tester.pumpAndSettle();
  await expectLater(
    find.byType(CheckoutButton),
    matchesGoldenFile('goldens/checkout_button_de.png'),
  );
});

import 'dart:convert';
import 'dart:io';
import 'package:test/test.dart';

void main() {
  test('all ARB files contain every key from the template', () {
    final l10nDir = Directory('lib/l10n');
    final templateFile = File('${l10nDir.path}/app_en.arb');
    final templateKeys = _extractKeys(templateFile);

    for (final file in l10nDir.listSync().whereType<File>()) {
      if (file.path == templateFile.path) continue;
      if (!file.path.endsWith('.arb')) continue;

      final translatedKeys = _extractKeys(file);
      final missing = templateKeys.difference(translatedKeys);
      expect(
        missing,
        isEmpty,
        reason: '${file.path} is missing keys: $missing',
      );
    }
  });
}

Set<String> _extractKeys(File file) {
  final map = jsonDecode(file.readAsStringSync()) as Map<String, dynamic>;
  return map.keys.where((k) => !k.startsWith('@')).toSet();
}

# In your CI pipeline
- name: Verify translations
  run: |
    flutter gen-l10n
    dart test test/l10n_completeness_test.dart

// WRONG
Text('Welcome back!')

// CORRECT
Text(AppLocalizations.of(context).welcomeBack)

# Catches obvious hardcoded user-facing strings in lib/
grep -rn "Text('[A-Z]" lib/ --include="*.dart" && echo "FAIL: hardcoded strings found" && exit 1

// WRONG: word order breaks in Japanese, Arabic, German, etc.
Text(l10n.hello + ', ' + userName + '!')

// CORRECT: use a parameterized message
Text(l10n.greeting(userName))

{
  "greeting": "Hello, {userName}!",
  "greeting_ja": "{userName}さん、こんにちは！"
}

// WRONG: will overflow in German
SizedBox(width: 100, child: Text(l10n.submitButton))

// CORRECT: let the layout breathe
ConstrainedBox(
  constraints: const BoxConstraints(minWidth: 80),
  child: Text(l10n.submitButton),
)

// Or simply use Flexible/Expanded in a Row

// WRONG: assumes US date format
Text('${date.month}/${date.day}/${date.year}')

// CORRECT: locale-aware
Text(DateFormat.yMd(Localizations.localeOf(context).toString()).format(date))

// WRONG
padding: const EdgeInsets.only(left: 16, right: 8)

// CORRECT
padding: const EdgeInsetsDirectional.only(start: 16, end: 8)

// WRONG: string is captured once and never updates on locale change
class _MyState extends State<MyWidget> {
  late final String title;

  @override
  void initState() {
    super.initState();
    title = AppLocalizations.of(context).pageTitle;  // also crashes — no InheritedWidget in initState
  }
}

// CORRECT: read in build, which re-runs on locale change
class _MyState extends State<MyWidget> {
  @override
  Widget build(BuildContext context) {
    final title = AppLocalizations.of(context).pageTitle;
    return Text(title);
  }
}