Flutter ARB Translation & gen-l10n

Requires Dart 3.12+, Flutter localization, and Node.js 22.16+.

1. Install the tooling and runtime

flutter pub add --dev translocale_flutter:^0.3.1
flutter pub add translocale_flutter_runtime:^0.1.3 translocale_delivery:^0.1.5
npm install --save-dev @translocale/cli@^0.6.1

2. Generate the adapter

Run from your Flutter project. Replace app.arb with the catalog name in TransLocale and choose your bundled target languages. Keep an existing manifest instead of running initialization again.

npx translocale flutter-init --catalog app.arb --targets fr,ar
npx translocale flutter-setup --file release-schema.json --catalog app.arb

Setup reads l10n.yaml and writes translocale_localizations.dart beside Flutter’s generated localizations. It does not translate or publish wording.

3. Publish a preview release

In your cloud project, approve the target translations. Open Releases, select the same catalogs and languages, and include your app’s version. Review the snapshot and publish it to Preview.

Need help with these dashboard steps? The illustrated setup guide shows project creation, catalog import, keys, review, and Preview publication. Use Flutter ARB for imports and the same catalog name across languages.

4. Connect app delivery

Sign in as a project owner. Replace PROJECT_UUID with your project ID.

npx translocale login --api https://translocale.io --project PROJECT_UUID --scope write
npx translocale flutter-connect --api https://translocale.io --project PROJECT_UUID --channel preview --file release-schema.json --out translocale.delivery.json

Keep the settings file out of source control. It contains a read-only delivery token. Authoring credentials stay in your tooling.

translocale.delivery*.json
.translocale-delivery-*.tmp

The dashboard’s Download configuration action creates translocale-delivery.json with fields such as projectId and deliveryToken. This Flutter example uses uppercase DELIVERY_* settings in translocale.delivery.json. Use flutter-connect above to generate that format; renaming the dashboard download does not convert its fields.

5. Wrap your app

Import the runtime and generated adapter. This example uses the default localization class; keep your existing theme, routes, and home widget.

import 'package:flutter/material.dart';
import 'package:translocale_flutter_runtime/translocale_flutter_runtime.dart';
import 'l10n/app_localizations.dart';
import 'l10n/translocale_localizations.dart';

void main() {
  WidgetsFlutterBinding.ensureInitialized();
  final delivery = FlutterDelivery(
    projectId: const String.fromEnvironment('DELIVERY_PROJECT'),
    schemaHash: translocaleSchemaHash,
    token: const String.fromEnvironment('DELIVERY_TOKEN'),
    channel: const String.fromEnvironment('DELIVERY_CHANNEL'),
    apiBaseUrl: const String.fromEnvironment('DELIVERY_ORIGIN'),
  );

  runApp(TransLocaleAppLocalizationsBuilder(
    delivery: delivery,
    builder: (context, delegates) => MaterialApp(
      localizationsDelegates: delegates,
      supportedLocales: AppLocalizations.supportedLocales,
      home: const HomePage(),
    ),
  ));
}

Adjust import paths to your generated folder. Create the runtime once; the wrapper manages refresh, lifecycle, and disposal.

flutter run --dart-define-from-file=translocale.delivery.json

Android release builds need the Internet permission. Use the same settings flag with flutter build.

<uses-permission android:name="android.permission.INTERNET" />

Ship and maintain

Test updates and rollback in Preview. Promote that release to Production, then create separate settings using --channel production. A preview credential cannot read production releases.

npx translocale flutter-setup --file release-schema.json --catalog app.arb --check

New keys or changed parameters need a compatible app build. Invalid updates retain cached or bundled wording. Web translation caching requires the app assets and version metadata to remain available.

Upgrading an existing app

From 0.1.0, keep your ARB files, authoring configuration, and AppLocalizations.of(context) calls. Add the runtime and wrapper above. From legacy 0.0.1, remove its runtime initialization and delegates, restore standard Flutter localizations, and create new delivery credentials. Legacy keys and caches do not transfer.

For use-escaping: true, retain the original service ARB and pass --source path/to/original.arb to flutter-init. Regional locales also need Flutter’s base-language ARB fallback.