# Flutter localization with TransLocale

Find ARB files, translate with your product context, and compile the downloaded wording with Flutter's localization generator.

Canonical page: https://translocale.io/integrations/flutter

## Install

translocale_flutter 0.3.2. Dart 3.12+ · macOS/Linux tooling. Message format: Flutter ARB, default escaping.

```bash
flutter pub add --dev translocale_flutter:^0.3.2
```

## Connect and configure

Create a cloud project under Projects → New project. Copy PROJECT_UUID from Project settings → Credentials, and match the project languages to your catalogs. Browser login stores authoring access outside the app. For CI, create a credential under Project settings → Credentials and put it in the TRANSLOCALE_TOKEN secret. App delivery uses a separate read-only credential under Releases → App delivery.

```bash
dart run translocale_flutter:translocale discover
dart run translocale_flutter:translocale init --api https://translocale.io --project PROJECT_UUID --locales en,fr,ar
```

```bash
dart run translocale_flutter:translocale login --scope translate
```

Configure Flutter localization in pubspec.yaml and l10n.yaml first. Setup reads those files and creates translocale.flutter.json without replacing catalogs. The check command runs flutter gen-l10n. Use the generated localizations in your widgets; the Dart tooling stays a development dependency.

## Translate and review

Inspect the plan before translating. The translate example starts a job capped at 1,000 source characters across target languages. Replace JOB_UUID with its returned ID. Save and review revision 1 before pulling it, or choose the exact revision you want to ship. Repeat pull for each target language. Normal builds do not start translation jobs.

```bash
dart run translocale_flutter:translocale plan
dart run translocale_flutter:translocale translate --max-characters 1000 --wait
dart run translocale_flutter:translocale pull --job JOB_UUID --locale fr --revision 1
dart run translocale_flutter:translocale check
```

The package discovers existing ARB catalogs from l10n.yaml. A pull refuses to replace an existing target: add --out candidates/fr.arb, review the candidate, and merge it manually. Use sync to preview a three-way merge against a recorded baseline, then apply its reviewed plan hash. Configured pulls record a baseline; candidate downloads leave it unchanged. Source metadata and the job's source snapshot must match before a download is accepted.

## Project setup and credentials

The screenshot walkthrough covers project creation, catalog import, keys, review, releases, and credentials. Use this framework’s message format and catalog identities. Authoring tokens belong in developer tools and CI; app delivery credentials only read published wording. Flutter’s flutter-connect writes DELIVERY_* build settings, while the dashboard download uses projectId, channel, schemaHash, deliveryToken, and apiBaseUrl.

- [Follow the illustrated first-project guide](https://translocale.io/docs/getting-started)

## Generate Flutter localizations from ARB files

Run flutter gen-l10n from your Flutter app directory after configuring its ARB input and Dart output. Merge the following entries into your existing pubspec.yaml, keeping its other dependencies and Flutter settings.

pubspec.yaml localization entries:

```yaml
dependencies:
  flutter:
    sdk: flutter
  flutter_localizations:
    sdk: flutter
  intl: any
flutter:
  generate: true
```

l10n.yaml:

```yaml
arb-dir: lib/l10n
template-arb-file: app_en.arb
output-dir: lib/generated
output-localization-file: app_localizations.dart
nullable-getter: false
use-escaping: false
required-resource-attributes: true
```

With this configuration, source and target files live in lib/l10n, and the generated API lives in lib/generated/app_localizations.dart. Keep use-escaping false for the TransLocale Flutter package's supported ARB import workflow.

lib/l10n/app_en.arb:

```json
{
  "@@locale": "en",
  "items": "{count, plural, =0 {Your cart is empty} =1 {One item} other {{count} items}}",
  "@items": {
    "description": "Number of items in the cart.",
    "placeholders": {
      "count": {
        "type": "int",
        "example": "3"
      }
    }
  }
}
```

lib/l10n/app_fr.arb:

```json
{
  "@@locale": "fr",
  "items": "{count, plural, =0 {Votre panier est vide} =1 {Un article} other {{count} articles}}",
  "@items": {
    "description": "Number of items in the cart.",
    "placeholders": {
      "count": {
        "type": "int",
        "example": "3"
      }
    }
  }
}
```

Resolve packages and generate Dart:

```bash
flutter pub get
flutter gen-l10n
```

Import lib/generated/app_localizations.dart from your app and configure MaterialApp with AppLocalizations.localizationsDelegates and AppLocalizations.supportedLocales. In a widget below MaterialApp, Text(AppLocalizations.of(context).items(3)) displays “3 items” in English or “3 articles” in French. nullable-getter: false makes the accessor non-nullable.

## Troubleshoot ARB plurals and generation errors

The count parameter has int metadata and an other fallback. The =0 and =1 selectors handle those exact values; {count} inside other inserts the quantity. Keep the same message key, parameter name and compatible metadata in the target catalog.

If generation cannot find the template, check arb-dir and template-arb-file against the actual source path. If generated imports fail, check output-dir and import that local output file. If a plural fails to parse, check its braces and other branch, then run the generator again.

Check an initialized TransLocale Flutter project:

```bash
dart run translocale_flutter:translocale check
```

The package check runs flutter gen-l10n. It can regenerate local Dart output, but it does not start a translation job. To compare the ARB source and target before generation, use the generic CLI check as well.

Compare existing ARB catalogs:

```bash
npx translocale check --source lib/l10n/app_en.arb --target lib/l10n/app_fr.arb --format arb
```

Choose Flutter ARB in the browser checker to inspect one source file. A syntax check does not establish translation quality; review the wording in each supported language before release.

- [Flutter internationalization and gen-l10n](https://docs.flutter.dev/ui/internationalization)
- [Check a source ARB file](https://translocale.io/app)
- [JSON and ARB format examples](https://translocale.io/docs#json-translation-examples)

## Compatibility and further setup

Strict-mode ARB imports with use-escaping: true are not supported. The separate main CLI can export strict-escaped files from service ARB.

File writes require the POSIX link utility. macOS is verified; Windows support and native device verification remain pending.

- [Complete framework guide, including runtime examples](https://translocale.io/integrations/flutter)
- [MCP guide](https://translocale.io/docs/mcp)
- [Free source file checker](https://translocale.io/app)