Flutter Internationalization

Flutter Internationalization

You are a Flutter localization implementer. Make localized apps build, generate, and read naturally across target locales.

Principle 0

Generated localization code must match the current Flutter project and SDK. Do not copy stale package:flutter_gen imports or enable synthetic-package; use source-generated AppLocalizations imports unless the project proves it is on an older pinned Flutter workflow.

Decision Guide

• Use gen-l10n for new work, most migrations, ARB management, plural/select

messages, generated AppLocalizations, and Material/Cupertino apps.

• Use legacy intl_translation only when the project already uses

Intl.message() plus generated messages_all.dart, or the user explicitly asks to keep that workflow. Confirm intl_translation is a dependency before running its generators.

• Use custom map-based localizations only for tiny prototypes or existing code

that intentionally avoids code generation. Name this limitation in the final response.

• If the project has an existing localization setup, follow its paths, class

names, locale list, and generation style before introducing defaults.

Workflow

1. Inspect pubspec.yaml, l10n.yaml, existing *.arb files, generated imports, MaterialApp/CupertinoApp setup, and current translation usage. 2. Identify the requested change: bootstrap l10n, add a locale, replace hardcoded UI text, add placeholders/plurals/selects, format values, fix generation, or migrate stale imports/config. 3. Use the decision guide to choose gen-l10n, legacy intl_translation, or a custom fallback. Prefer the smallest change that fits the existing project. 4. Read only the routed references needed for the task. 5. Make the localization change:

• add flutter_localizations and intl:any when missing;
• set flutter: generate: true;
• create or update l10n.yaml;
• create or update ARB files with descriptions and placeholder metadata;
• wire AppLocalizations into MaterialApp or CupertinoApp;
• replace hardcoded UI strings with generated getters or methods.

6. Generate and validate with flutter gen-l10n. Then run the narrowest relevant project check, usually flutter analyze or affected tests. 7. Report changed files, generated behavior, validation run, and any locales or translation gaps that remain.

Resource Routing

gen-l10n Contract

For new gen-l10n setup, the minimum current configuration is:

flutter:
  generate: true

arb-dir: lib/l10n
template-arb-file: app_en.arb
output-localization-file: app_localizations.dart

Use source imports that match the generated location, commonly:

import 'l10n/app_localizations.dart';

Prefer generated lists when possible:

localizationsDelegates: AppLocalizations.localizationsDelegates,
supportedLocales: AppLocalizations.supportedLocales,

If generated files are written to a custom output-dir, update imports to that directory. Do not import package:flutter_gen/gen_l10n/app_localizations.dart unless the local project is intentionally pinned to an older Flutter workflow.

Legacy Intl Fallback

When preserving Intl.message():

• require intl_translation in dev dependencies before extraction/generation;
• keep generated files and imports consistent with the existing project;
• run extraction before generation;
• on Windows or shells without wildcard expansion, list ARB files explicitly.

Typical commands:

dart run intl_translation:extract_to_arb --output-dir=lib/l10n lib/main.dart
dart run intl_translation:generate_from_arb --output-dir=lib/l10n --no-use-deferred-loading lib/main.dart lib/l10n/intl_*.arb

If this workflow is not already present, explain why gen-l10n is the safer default.

Constraints

• Do not invent translations. If target-language text is not supplied, add clear

placeholder translations only when the user approved that, or report the missing translations.

• Do not concatenate localized strings. Use placeholders, plural, or select

messages.

• Do not manually format numbers, currency, percentages, dates, or times when

gen-l10n placeholder formatting can do it.

• Do not add synthetic-package: true; current Flutter marks synthetic package

generation as deprecated and unavailable.

• Set nullable-getter: false only when the project accepts non-null generated

getter behavior. Otherwise keep the project default and use the required null handling in code.

• Keep translator-facing descriptions and examples in the template ARB file.
• For RTL locales, check text direction, layout assumptions, mirrored icons, and

locale-specific widgets.

Validation

Always validate a completed localization change:

• flutter gen-l10n succeeds with the project's l10n.yaml;
• generated import paths compile;
• every new ARB key exists in the template file and needed locale files;
• placeholders in translated ARB values match template metadata;
• plural/select messages include other;
• number/date placeholders use supported formats from

references/number-date-formats.md;

• relevant flutter analyze or tests pass, or blockers are reported.

For skill maintenance, also check YAML frontmatter, local markdown links, JSON validity for ARB assets, YAML validity for l10n.yaml, resource routing, and layer coherence between SKILL.md, references, and assets.

ARB File Format Reference

Complete reference for App Resource Bundle (.arb) files used by Flutter's gen-l10n tool.

ARB File Basics

ARB files are JSON files containing localization resources with metadata.

Basic Structure

{
  "messageKey": "Message value",
  "@messageKey": {
    "description": "Message description for translators"
  }
}

Template File

The template file (typically app_en.arb) contains all keys with their English translations and metadata:

{
  "helloWorld": "Hello World!",
  "@helloWorld": {
    "description": "The conventional newborn programmer greeting"
  }
}

Translation File

Translation files (e.g., app_es.arb) only contain translated values:

{
  "helloWorld": "¡Hola Mundo!"
}

Message Types

Simple Messages

Basic text without parameters:

{
  "welcome": "Welcome to our app",
  "@welcome": {
    "description": "Welcome message shown on home screen",
    "type": "text"
  }
}

Placeholder Messages

Messages with dynamic values:

{
  "hello": "Hello {userName}",
  "@hello": {
    "description": "A message with a single parameter",
    "placeholders": {
      "userName": {
        "type": "String",
        "example": "Bob"
      }
    }
  }
}

Plural Messages

Messages that change based on count:

{
  "nWombats": "{count, plural, =0{no wombats} =1{1 wombat} other{{count} wombats}}",
  "@nWombats": {
    "description": "A plural message",
    "placeholders": {
      "count": {
        "type": "num",
        "format": "compact"
      }
    }
  }
}

Plural forms: =0, =1, =2, zero, one, two, few, many, other

Select Messages

Messages that change based on a string value:

{
  "pronoun": "{gender, select, male{he} female{she} other{they}}",
  "@pronoun": {
    "description": "A gendered message",
    "placeholders": {
      "gender": {
        "type": "String"
      }
    }
  }
}

Select matching is case-sensitive. For example, Male does not match male and falls back to other, so normalize values before passing them to generated localization methods.

Placeholder Types

String

{
  "greeting": "Hello {name}",
  "@greeting": {
    "placeholders": {
      "name": {
        "type": "String",
        "example": "Alice"
      }
    }
  }
}

Number Formatting

{
  "price": "Price: {value}",
  "@price": {
    "placeholders": {
      "value": {
        "type": "int",
        "format": "compactCurrency",
        "optionalParameters": {
          "decimalDigits": 2,
          "symbol": "$"
        }
      }
    }
  }
}

Date Formatting

{
  "eventDate": "Event on {date}",
  "@eventDate": {
    "placeholders": {
      "date": {
        "type": "DateTime",
        "format": "yMd"
      }
    }
  }
}

Number Format Options

See number-date-formats.md for the complete list of number and date format options.

Date Format Options

Common DateFormat patterns:

Metadata Attributes

Required Attributes for Complex Messages

For messages with placeholders, plurals, or selects:

{
  "message": "Text with {placeholder}",
  "@message": {
    "description": "Message description",
    "placeholders": {
      "placeholder": {
        "type": "String"
      }
    }
  }
}

Optional Attributes

{
  "message": "Text",
  "@message": {
    "description": "Message description",
    "type": "text",
    "context": "Context for disambiguation"
  }
}

Escaping Syntax

Enable escaping in l10n.yaml:

use-escaping: true

Then use single quotes to escape special characters:

{
  "escaped": "Hello! '{Isn''t}' this a wonderful day?"
}

Results in: Hello! {Isn't} this a wonderful day?

Complete Example

{
  "appTitle": "My App",
  "@appTitle": {
    "description": "Application title"
  },
  "greeting": "Hello {userName}!",
  "@greeting": {
    "description": "Personalized greeting message",
    "placeholders": {
      "userName": {
        "type": "String",
        "example": "John"
      }
    }
  },
  "itemCount": "{count, plural, =0{No items} =1{1 item} other{{count} items}}",
  "@itemCount": {
    "description": "Number of items in cart",
    "placeholders": {
      "count": {
        "type": "int"
      }
    }
  },
  "pronoun": "{gender, select, male{he} female{she} other{they}}",
  "@pronoun": {
    "description": "Gender-based pronoun",
    "placeholders": {
      "gender": {
        "type": "String"
      }
    }
  },
  "orderDate": "Ordered on {date}",
  "@orderDate": {
    "description": "Order confirmation with date",
    "placeholders": {
      "date": {
        "type": "DateTime",
        "format": "yMMMd"
      }
    }
  }
}

Best Practices

1. Use descriptive keys: userProfileTitle instead of title1 2. Provide examples: Help translators understand context 3. Use type annotations: Improves generated code type safety 4. Add descriptions: Provide context for translators 5. Keep messages short: Make them easier to translate 6. Use placeholders: Don't concatenate strings 7. Format numbers/dates: Let Flutter handle localization

l10n.yaml Configuration

Reference for l10n.yaml options used by Flutter's gen-l10n tool. Treat flutter gen-l10n --help in the user's project as the final source of truth when an installed SDK differs from these notes.

Basic Configuration

arb-dir: lib/l10n
template-arb-file: app_en.arb
output-localization-file: app_localizations.dart

Output Location

By default, current Flutter generates localization source into the ARB directory or the configured output-dir. Import the generated file from that source location:

import 'l10n/app_localizations.dart';

Use a custom output directory only when the project wants generated files outside arb-dir:

arb-dir: lib/l10n
template-arb-file: app_en.arb
output-localization-file: app_localizations.dart
output-dir: lib/generated/l10n

Then import from that directory:

import 'generated/l10n/app_localizations.dart';

Do not configure synthetic-package: true. Current Flutter marks the synthetic package flag as deprecated and it cannot be enabled. Migrate stale imports like package:flutter_gen/gen_l10n/app_localizations.dart to source imports that match the generated output location.

Locale Options

preferred-supported-locales:
  - en_US
  - es_ES

preferred-supported-locales changes the generated supported-locale order. Use it when the app should prefer a specific regional locale instead of alphabetical ordering.

Code Generation Options

Use nullable-getter: false only when the project accepts non-null generated getter behavior:

arb-dir: lib/l10n
template-arb-file: app_en.arb
output-localization-file: app_localizations.dart
nullable-getter: false

With the default nullable getter, user code usually needs:

AppLocalizations.of(context)!.title

With nullable-getter: false, the generated getter performs the null check and call sites can omit !:

AppLocalizations.of(context).title

Tracking And Warnings

Track untranslated messages when adding or auditing locale coverage:

arb-dir: lib/l10n
template-arb-file: app_en.arb
output-localization-file: app_localizations.dart
untranslated-messages-file: l10n_untranslated.json

Deferred Loading

Deferred loading can reduce initial JavaScript bundle size for web apps with many locales and many messages. It can add overhead for small locale sets, and it does not affect mobile or desktop.

arb-dir: lib/l10n
template-arb-file: app_en.arb
output-localization-file: app_localizations.dart
use-deferred-loading: true

Use the normal generated source import:

import 'l10n/app_localizations.dart';

Future<AppLocalizations> loadLocale(String localeCode) {
  return AppLocalizations.delegate.load(Locale(localeCode));
}

Header Configuration

header: "/// Generated localization files."

For a longer header, place the file in arb-dir:

lib/l10n/header.txt

Then configure:

header-file: header.txt

Validation

After changing l10n.yaml:

1. Run flutter gen-l10n. 2. Confirm generated files appear in arb-dir or output-dir. 3. Confirm app imports match the generated location. 4. Run the narrowest relevant compile check, usually flutter analyze.

For placeholder number and date formats, see number-date-formats.md.

Number and Date Formatting

Complete reference for number and date formatting in Flutter internationalization.

Number Formatting

Basic Number Formats

Supported placeholder types: int, double, num

Currency Formats

Currency with Default Symbol

{
  "price": "Price: {value}",
  "@price": {
    "placeholders": {
      "value": {
        "type": "int",
        "format": "currency"
      }
    }
  }
}

Currency with Custom Symbol

{
  "price": "Price: {value}",
  "@price": {
    "placeholders": {
      "value": {
        "type": "int",
        "format": "simpleCurrency",
        "optionalParameters": {
          "symbol": "€"
        }
      }
    }
  }
}

Compact Currency

{
  "followers": "{count} followers",
  "@followers": {
    "placeholders": {
      "count": {
        "type": "int",
        "format": "compactCurrency"
      }
    }
  }
}

Decimal Places Control

{
  "price": "Price: {value}",
  "@price": {
    "placeholders": {
      "value": {
        "type": "double",
        "format": "compactCurrency",
        "optionalParameters": {
          "decimalDigits": 2
        }
      }
    }
  }
}

Percentage

{
  "progress": "Progress: {value}",
  "@progress": {
    "placeholders": {
      "value": {
        "type": "double",
        "format": "percentPattern"
      }
    }
  }
}

Date Formatting

DateFormat Patterns

Supported placeholder type: DateTime

Common Date Formats

{
  "eventDate": "Event on {date}",
  "@eventDate": {
    "placeholders": {
      "date": {
        "type": "DateTime",
        "format": "yMd"
      }
    }
  }
}

Full Date Formats

Relative Time

For relative time (e.g., "2 minutes ago"), use intl package directly:

import 'package:intl/intl.dart';

final timeAgo = DateFormat('jm').format(DateTime.now().subtract(Duration(minutes: 2)));

Platform-Specific Formatting

Flutter automatically formats numbers and dates according to locale. Examples:

English (en_US)

• Numbers: 1,234,567.89
• Currency: $1,234.57
• Date: January 15, 2024

Spanish (es_ES)

• Numbers: 1.234.567,89
• Currency: 1.234,57 €
• Date: 15 de enero de 2024

French (fr_FR)

• Numbers: 1 234 567,89
• Currency: 1 234,57 €
• Date: 15 janvier 2024

German (de_DE)

• Numbers: 1.234.567,89
• Currency: 1.234,57 €
• Date: 15. Januar 2024

Russian (ru_RU)

• Numbers: 1 234 567,89
• Currency: 1 234,57 ₽
• Date: 15 января 2024

Best Practices

1. Use locale-aware formatting: Always specify format for numbers/dates 2. Don't format manually: Let Flutter handle locale-specific formatting 3. Test across locales: Verify formatting in target locales 4. Use compact for large numbers: Makes UI more readable 5. Consider context: Use currency symbol appropriate for audience 6. Handle special cases: Some languages have unique formatting rules

Common Patterns

Price Display

{
  "itemPrice": "Price: {price}",
  "@itemPrice": {
    "placeholders": {
      "price": {
        "type": "double",
        "format": "simpleCurrency"
      }
    }
  }
}

Count Display

{
  "itemCount": "{count, plural, =0{No items} =1{1 item} other{{count} items}}",
  "@itemCount": {
    "placeholders": {
      "count": {
        "type": "int",
        "format": "compact"
      }
    }
  }
}

Date Range

{
  "dateRange": "From {start} to {end}",
  "@dateRange": {
    "placeholders": {
      "start": {
        "type": "DateTime",
        "format": "yMMMd"
      },
      "end": {
        "type": "DateTime",
        "format": "yMMMd"
      }
    }
  }
}