Localize a Flutter app

Translate ARB messages, generate Flutter resources, and check the resulting screen in each target locale.

Flutter's localization tools turn ARB messages into the methods your widgets call. Lingo.dev translates those ARB resources, so you can keep the same generated API while adding languages. Start with one screen whose greeting and item count let you check text, variables, and plural behavior together.

This procedure assumes the project already loads its source ARB through Flutter localization generation. Keep the existing l10n.yaml, generator, and widget calls. Lingo.dev handles file translation here; Flutter continues to select the locale and render the messages.

Give each message the information it needs #

For a source at lib/l10n/app_en.arb, use a catalog such as:

json
{
  "@@locale": "en",
  "welcome": "Welcome, {name}",
  "@welcome": {
    "description": "Greeting on the signed-in account screen",
    "placeholders": { "name": { "type": "String" } }
  },
  "itemCount": "{count, plural, =0{No items} =1{One item} other{{count} items}}",
  "@itemCount": {
    "description": "Number of items in the cart",
    "placeholders": { "count": { "type": "int" } }
  }
}

The description explains the message's use to the translator. Placeholder definitions tell Flutter what values the caller supplies. The ARB handler translates the two message strings, retains the metadata, and changes the existing @@locale field to the target locale.

Run the project's localization generator on the source first and use the generated greeting and count methods in the screen. This establishes that the original catalog and caller agree before another language is introduced.

Install and authenticate the current CLI from the project root:

sh
npm install --global @lingo.dev/cli
lingo login
lingo init --source en --targets de,fr --files 'lib/l10n/app_en.arb' --yes
lingo link

init writes .lingo/config.json; link selects the organization and localization engine. Keep the generated identifiers. The localization fields should select only the source file:

json
{
  "sourceLocale": "en",
  "targetLocales": ["de", "fr"],
  "files": [
    { "pattern": "lib/l10n/app_en.arb", "format": "flutter" }
  ]
}

This is the localization portion of the linked configuration, not a replacement for its organization and localization engine IDs. The .arb extension also selects flutter automatically. This layout produces app_de.arb and app_fr.arb; confirm that the project's generator reads them. For another layout, set an explicit target path.

Avoid a source pattern such as app_*.arb that also selects translated catalogs. For regional locales, align filename spelling with the Flutter project's configuration rather than assuming every locale string works unchanged in a filename.

Translate and generate the target resources #

For missing target files, run:

sh
lingo push --backfill-missing --wait

The command waits for completion and retrieves the files. If the run waits for review or fails, resolve that state before generating release resources. A plain first push can establish the source baseline without requesting these missing translations.

Inspect the target keys, descriptions, placeholder names and types, and @@locale. Then run the project's Flutter localization generation, analysis, tests, and build. Repair any invalid ICU expression, missing placeholder, or incompatible type before proceeding. ARB reconstruction preserves metadata but does not validate every translated message against Flutter's generator.

Open the screen in German and French. Supply a short name and a long name, then counts of 0, 1, 2, and a larger number. Read the plural wording rather than checking only that a number appeared. Languages can require categories beyond the English source, so review the necessary target forms. Check locale selection, fallback, text expansion, and direction where relevant. Date and number formatting remain Flutter runtime decisions.

Keep later updates tied to the source #

Keep configuration, source, accepted targets, and .lingo/lock.json together. After changing a source message, run lingo push --wait and inspect that message beside an unchanged neighboring message. A description-only edit does not itself make the message text a new translation task; use a bounded update when revised context should cause retranslation.

Do not edit target files while waiting writeback is active. To protect local target corrections, submit without --wait, inspect lingo pull --dry-run, and then retrieve with lingo pull in the submitting checkout. Other machines need committed translations or an explicit artifact handoff, not an assumed shared last run. See Preserve reviewed translations for recovery details.

Once this cycle works, use the GitHub App or CI automation to repeat translation and resource generation before review. Native Android XML and Apple resources have different file and runtime contracts; keep them separate from ARB generation in a cross-platform project.