Code generation and gen_l10n

The generator is a development dependency. It does not ship analyzer or YAML parsing in the application runtime. Generation reads application-owned ARB files or a verified signed release package. Existing project keys are never renamed to fit Dart identifiers.

Install the optional generator

The generator is not published to pub.dev. Use the immutable v0.1.0 release tag as a Git development dependency alongside localisync_sdk: ^0.1.0:

dev_dependencies:
  localisync_generator:
    git:
      url: https://github.com/wetuscorp/localisync_flutter_sdk.git
      ref: v0.1.0
      path: tool/generator

The generator resolves the same localisync_sdk package as the application. No dependency overrides are needed for this registry/Git installation. For source development, use the repository workspace. Never add analyzer to runtime dependencies.

Typed accessors from ARB

Create a localisync.yaml next to your application’s pubspec.yaml:

arb:
  en: lib/l10n/app_en.arb
  tr: lib/l10n/app_tr.arb
fallbacks:
  en: null
  tr: en
output: lib/generated/localisync_messages.dart
names:
  checkout.success: checkoutSuccess

Run dart run localisync_generator:generate localisync.yaml. The output contains the baseline, shared contracts and typed getters/methods. Numeric placeholders use num, text uses String. Each locale needs an explicit fallback declaration; all chains terminate at the source locale. Name collisions, incompatible placeholder contracts and invalid ICU stop generation. Declare placeholder metadata explicitly. useEscaping: false is the default, matching Flutter’s default ARB behavior. Set useEscaping: true when l10n.yaml enables use-escaping; this also decodes escaped literal braces in messages with no arguments. The generator rejects ambiguous inputs, unknown options and outputs that overwrite an input/configuration file. Keep generated files separate from original gen_l10n output.

Preserve AppLocalizations

First run Flutter’s flutter gen-l10n with output in your source directory. Add an adapter section pointing at the generated public class:

adapter:
  source: lib/l10n/generated/app_localizations.dart
  output: lib/generated/localisync_delegate.dart
  import: ../l10n/generated/app_localizations.dart

Run the Localisync generator after Flutter generation. In MaterialApp.localizationsDelegates, replace only AppLocalizations.delegate with LocalisyncAppLocalizationsDelegate(client). Keep the Material, Widgets and Cupertino delegates. Rebuild the delegate from a widget that uses LocalisyncScope.of(context) so its captured content version advances. Existing calls such as AppLocalizations.of(context).greeting(name) remain unchanged.

The adapter forwards unsupported date/number formats to the application’s original delegate. Generation reports those keys as Bundled delegate only. It does not silently convert them to OTA Plain text. The runnable examples/gen_l10n demonstrates this with a formatted date.

New generated methods and additional compiled Flutter locales require an application build. A remote release cannot add Dart methods or expand the original delegate’s supported locales.

Baseline from a signed release

Copy public SDK setup to a local JSON file and add channel and appVersion. Supply the read key through LOCALISYNC_READ_KEY, using your build system’s secret input rather than a committed file. Run:

dart run localisync_generator:download localisync.sdk.json release.json en tr

The tool verifies catalog and release signatures, version compatibility, file lengths and hashes. It downloads the requested locales and their explicit fallback chains from one immutable release. For generation, set release: release.json, trustedKeys (public keys only), output, and any names mappings in localisync.yaml. Do not also configure an ARB input.

Release input is verified again before code is generated. A corrupt package never becomes a compiled baseline. Review the generated changes and commit the baseline with the application.