l10n_flow #

English | 中文文档

Collaborative localization for Flutter. Sync a published Google Sheet to JSON, validate translation quality, and consume the resources through a lightweight runtime manager.

Features #

• Public Google Sheets TSV source; no service account required
• sync, validate, and watch CLI commands
• JSON output with safe stale-file cleanup
• Duplicate-key, empty-value, and placeholder validation
• Runtime locale switching and locale resolution
• Named and ordered interpolation
• Remote translation patches and global placeholders
• Missing-key stream, .tr extensions, L10nBuilder, and TextTr

Install #

dependencies:
  flutter_localizations:
    sdk: flutter
  l10n_flow: ^0.1.0

Configure #

Publish a Google Sheet as TSV. A typical sheet looks like:

The published URL must use output=tsv. CSV URLs such as output=csv are not supported by the current Google Sheets source.

Add a root-level section to your app's pubspec.yaml:

l10n_flow:
  source:
    type: google_sheets_tsv
    url: https://docs.google.com/spreadsheets/d/e/YOUR_ID/pub?output=tsv
  # Generated JSON directory, relative to the directory where the command runs.
  output: assets/l10n
  # 1-based row containing Key and language column headers.
  # Use 2 when row 1 is a document title and row 2 contains the headers.
  header_row: 1
  # Exact column header containing translation keys.
  key_header: Key
  # Non-language columns that should not generate locale files.
  exclude_columns:
    - Notes
  # Sheet column header -> generated JSON filename (without .json).
  languages:
    English: en
    Simplified Chinese: zh_cn
    Vietnamese: vi

The keys under languages must exactly match the language column headers in the sheet. English header names are recommended for shared demo projects.

Register the generated directory as a Flutter asset:

flutter:
  assets:
    - assets/l10n/

CLI #

dart run l10n_flow sync
dart run l10n_flow validate
dart run l10n_flow watch

Use another project configuration file when needed:

dart run l10n_flow sync --config path/to/pubspec.yaml

sync returns exit code 2 when quality warnings are found, making it suitable for CI checks.

Flutter runtime #

const english = AppLocale(
  value: Locale('en'),
  assetPath: 'assets/l10n/en.json',
);
const chinese = AppLocale(
  value: Locale('zh', 'CN'),
  assetPath: 'assets/l10n/zh_cn.json',
);

await L10nManager().init(
  defaultLocale: english,
  locales: const [english, chinese],
  placeholders: const {'{brand}': 'Acme'},
);

Read translations:

Text('app.title'.tr);
Text('welcome'.trMap({'name': 'Aiwen'}));
Text('score'.trValues([2, 1]));

Rebuild automatically after a locale change:

L10nBuilder(
  builder: (context, l10n) => MaterialApp(
    locale: l10n.locale.value,
    supportedLocales: L10nManager().supportedLocales,
    localizationsDelegates: GlobalMaterialLocalizations.delegates,
    home: const HomePage(),
  ),
);

Import GlobalMaterialLocalizations from package:flutter_localizations/flutter_localizations.dart. Wrapping the root MaterialApp lets both application translations and Flutter's Material and Cupertino widgets react to locale changes.

Convenience widgets and rich text:

TextTr('welcome', named: {'name': 'Aiwen'});

'demo.rich_message'.rich(
  defaultStyle: const TextStyle(color: Colors.black),
  named: {
    'terms': 'Terms of Service',
    'privacy': 'Privacy Policy',
  },
  styleMap: {
    'terms': const TextStyle(color: Colors.blue),
    'privacy': const TextStyle(color: Colors.blue),
  },
);

Switch locales:

await L10nManager().change(chinese);

Apply server-side patches without replacing bundled JSON:

await L10nManager().merge({
  chinese: {'campaign.title': '限时活动'},
});

Listen for missing keys:

L10nManager().missingKeyStream.listen(logMissingTranslation);

Runnable example #

The example/ directory is a complete Flutter application for Android, iOS, web, macOS, Linux, and Windows. It demonstrates English, Simplified Chinese, and Vietnamese locale switching against a published demo Google Sheet.

cd example
flutter pub get
dart run l10n_flow sync
flutter run

Configuration reference #

For example, given this sheet:

Row 1: L10n Flow Demo
Row 2: Key | English | Simplified Chinese | Vietnamese
Row 3: app.title | L10n Flow Demo | L10n Flow 示例 | Demo L10n Flow

set header_row: 2, because row 2 contains the column headers. Translation data starts on the following row.

License #

MIT