Skip to content
Tutorials Center
My learning

Topics

Lesson 57 of 73 · Quality and performance

Accessibility and Internationalization

Make Flutter apps usable by everyone: Semantics and screen readers, text scaling, contrast, and localization with intl, ARB files, plurals and right-to-left layouts.

Two questions decide how many people can actually use your app. Can someone use it without seeing the screen, with large text, or with limited motor control? That is accessibility (often shortened to a11y). And can someone use it in their language, with their date format and reading direction? That is internationalization (i18n) for building the capability and localization (l10n) for supplying each language.

Flutter handles much of both for you, but only if you build with them in mind. This lesson shows the tools: Semantics, text scaling, contrast, and the intl and ARB workflow with plurals and right-to-left (RTL) layouts.

Real vs stand-in. The Dart, YAML and JSON are real, read-only code: the site has no Flutter runtime, screen reader or device locale. The live examples are JavaScript stand-ins: a semantics tree read aloud as text, a contrast calculator and a plural-aware message formatter.

Accessible means

Perceivable Contrast, text size, labels.
Operable Big targets, focus order.
Understandable Clear text, helpful errors.
Screen-reader ready Every control has a name.
1 / 2

Semantics: the tree screen readers use

Flutter draws its own pixels, so the operating system cannot look inside and discover buttons and labels. Instead Flutter builds a parallel semantics tree: a simplified description of what is on screen (labels, roles, actions) that TalkBack (Android), VoiceOver (iOS) and browser accessibility tools read.

The good news: standard widgets add semantics automatically. ElevatedButton, TextField, Checkbox, Switch and Text already describe themselves. The work is in the gaps.

DART
// An icon button with no text: a screen reader says nothing useful.
IconButton(
  icon: const Icon(Icons.delete),
  onPressed: onDelete,
)

// Fix: give it a tooltip (used as the label and shown on long press).
IconButton(
  icon: const Icon(Icons.delete),
  tooltip: 'Delete message',
  onPressed: onDelete,
)

For custom widgets, wrap them in Semantics:

DART
Semantics(
  label: 'Rating',
  value: '4 out of 5 stars',
  child: const StarRow(filled: 4),
)

Semantics(
  button: true,
  label: 'Play preview',
  onTap: play,
  child: GestureDetector(onTap: play, child: const PlayArtwork()),
)

Useful properties: label (what it is), value (current value), hint (what happens), button, header, image, liveRegion (announce changes), enabled, selected and onTap. Two helpers manage noise:

  • ExcludeSemantics removes purely decorative content from the tree (a background swirl, an icon repeated next to its text).
  • MergeSemantics combines several children into one announcement, so "Price" and "$12" are read as one item.

Images need semanticLabel (or excludeFromSemantics: true for decoration):

DART
Image.asset('assets/chart.png', semanticLabel: 'Sales rose 20% in March');
JS What a screen reader would say

Press Run (or Ctrl + Enter) to see the console output here.

No output.

The merged item is read as one stop, the decorative swirl is skipped, and the unlabeled button is exactly the kind of bug that makes an app unusable for a blind user. Real-world audits are mostly about finding items like it.

Testing semantics

You can check labels in a widget test (testing):

DART
testWidgets('delete button has a label', (tester) async {
  final handle = tester.ensureSemantics();
  await tester.pumpWidget(const MaterialApp(home: InboxPage()));

  expect(find.bySemanticsLabel('Delete message'), findsOneWidget);
  handle.dispose();
});

// Built-in guideline checks:
await expectLater(tester, meetsGuideline(androidTapTargetGuideline));
await expectLater(tester, meetsGuideline(labeledTapTargetGuideline));
await expectLater(tester, meetsGuideline(textContrastGuideline));

Then test by hand: turn on TalkBack or VoiceOver and try to complete the main flow with your eyes closed. Nothing replaces that.

Text scaling and layout

Many people raise the system font size. Flutter respects it through MediaQuery.textScalerOf(context), and Text scales automatically. Layouts must survive 200% text:

  • Do not hard-code heights for text containers; let them size to content (padding and sizing).
  • Use Flexible/Expanded or Wrap so labels can wrap instead of overflowing (Row and Column).
  • Make long screens scrollable.
  • Never turn scaling off. If one place needs a cap, limit it with TextScaler.linear(...).clamp(maxScaleFactor: 1.5) rather than disabling it.

Touch targets, focus and motion

  • Target size: keep tappable areas at least about 48 × 48 logical pixels. Material buttons do this by default; custom GestureDetector icons often do not. Wrap them in InkResponse with padding or SizedBox.
  • Keyboard and focus order: desktop and web users tab through controls. Use FocusTraversalGroup and FocusTraversalOrder if the default reading order is wrong, and make sure custom controls can take focus (Focus, FocusableActionDetector).
  • Reduce motion: when MediaQuery.disableAnimationsOf(context) is true, skip long or flashy animations.
  • Do not rely on color alone: an error should show an icon or text, not only a red border.

Contrast

Text must stand out from its background. WCAG, the common accessibility standard, asks for a contrast ratio of at least 4.5:1 for normal text and 3:1 for large text. The ratio compares the relative luminance of the two colors. Material 3's ColorScheme.fromSeed produces accessible pairs such as primary and onPrimary; custom colors are where you need to check (themes).

JS WCAG contrast ratio calculator

Press Run (or Ctrl + Enter) to see the console output here.

No output.

Light gray and yellow on white look "clean" in a design file and fail for many real users, especially in sunlight.

Internationalization with intl and ARB files

Flutter's official localization path generates Dart code from ARB (Application Resource Bundle) files, which are JSON with a few conventions. The setup has four pieces.

1. Dependencies and config.

YAML
# pubspec.yaml
dependencies:
  flutter:
    sdk: flutter
  flutter_localizations:
    sdk: flutter
  intl: any

flutter:
  generate: true
YAML
# l10n.yaml
arb-dir: lib/l10n
template-arb-file: app_en.arb
output-localization-file: app_localizations.dart

2. The template ARB file (English) defines keys, placeholders and plurals:

JSON
{
  "@@locale": "en",
  "appTitle": "Bookshelf",
  "greeting": "Hello, {name}!",
  "@greeting": {
    "description": "Shown on the home page",
    "placeholders": { "name": { "type": "String" } }
  },
  "unreadCount": "{count, plural, =0{No unread messages} =1{One unread message} other{{count} unread messages}}",
  "@unreadCount": {
    "placeholders": { "count": { "type": "int" } }
  }
}

3. Translations in app_es.arb, app_ar.arb and so on use the same keys:

JSON
{
  "@@locale": "es",
  "appTitle": "Estantería",
  "greeting": "¡Hola, {name}!",
  "unreadCount": "{count, plural, =0{Sin mensajes nuevos} =1{Un mensaje nuevo} other{{count} mensajes nuevos}}"
}

4. Wire it into the app. flutter pub get (or flutter gen-l10n) generates AppLocalizations:

DART
MaterialApp(
  localizationsDelegates: AppLocalizations.localizationsDelegates,
  supportedLocales: AppLocalizations.supportedLocales,
  home: const HomePage(),
)

// In a widget:
final l10n = AppLocalizations.of(context)!;
Text(l10n.greeting('Ada'));
Text(l10n.unreadCount(3));

Because the strings are generated methods, a missing placeholder is a compile error instead of a runtime surprise. The locale follows the device setting; users can also override it with MaterialApp(locale: ...).

Plurals are not just singular and plural

English has two forms. Russian has four categories (one, few, many, other), Arabic has six, and Japanese has just one. The ICU syntax in ARB handles all of them: you write the forms each language needs, and the plural rules choose among them. Never build messages with count == 1 ? 'item' : 'items' in code, because it silently breaks for most languages.

Also never concatenate sentence pieces ('Hello, ' + name + '!'): word order differs between languages, so each message must be one complete string with placeholders.

JS A tiny ICU-style plural formatter

Press Run (or Ctrl + Enter) to see the console output here.

No output.

The Russian row changes the form for 1, 2, 5 and 21, which is why one hard-coded s can never be right. Flutter's generated code uses the same CLDR plural rules as Intl.PluralRules.

Dates, numbers and currency

Use intl formatters with the current locale instead of building strings by hand:

DART
final locale = Localizations.localeOf(context).toString();

DateFormat.yMMMMd(locale).format(date);          // "March 5, 2026" or "5 de marzo de 2026"
NumberFormat.decimalPattern(locale).format(1234567.5);
NumberFormat.currency(locale: locale, symbol: '€').format(19.9);

Remember that currency conversion is a business problem, not a formatting one: formatting only changes how the number looks.

Right-to-left (RTL) layouts

Arabic, Hebrew, Persian and Urdu read right to left. Flutter flips most layouts automatically when the locale is RTL: Row children reverse, the back arrow moves, drawers open from the other side. This works if you use directional values:

DART
// Hard-coded left/right: wrong in RTL.
Padding(padding: const EdgeInsets.only(left: 16), child: child)
Align(alignment: Alignment.centerLeft, child: child)

// Directional: flips with the language.
Padding(padding: const EdgeInsetsDirectional.only(start: 16), child: child)
Align(alignment: AlignmentDirectional.centerStart, child: child)

Other things that need care: icons that imply direction (an arrow or "reply") may need mirroring (Icon(..., textDirection: ...) or the matchTextDirection property for images), numbers and Latin words inside RTL text keep their own direction, and text length varies by language (German is often 30% longer than English), which is one more reason layouts must flex (responsive layouts).

A localization checklist

  • Every user-visible string comes from the ARB files, including error messages and tooltips.
  • Strings use placeholders and ICU plurals, never concatenation.
  • Layouts use EdgeInsetsDirectional and AlignmentDirectional.
  • Dates, numbers and currencies use intl with the active locale.
  • You run the app in a long language (German) and an RTL language (Arabic) before release, with large text enabled.

Accessibility and localization reach far more people than you expect, and fixing them late is expensive. Next, make failures visible and recoverable: Error Handling, Logging and Crash Reporting.

Check your understanding

Quick check · 5 questions

of 5 answered You scored / 5 · perfect!

  1. 1. Why does an IconButton with only an icon and no tooltip cause an accessibility problem?

    Without a tooltip or Semantics label the semantics tree has no name for the control, so TalkBack or VoiceOver cannot say what it does.
  2. 2. What is the minimum WCAG contrast ratio for normal-size text?

    Normal text needs 4.5:1. Large text can use 3:1.
  3. 3. Which approach is correct for pluralized text in many languages?

    Languages have different plural categories. ICU plural syntax lets each translation supply the right forms.
  4. 4. Which EdgeInsets variant adapts correctly to right-to-left languages?

    Directional values use start and end, which flip with the text direction.
  5. 5. A user sets the system font to 200%. What should your layout do?

    Respect text scaling. Flexible layouts and scrollable screens keep content readable.

Summary

  • Flutter builds a semantics tree for screen readers; standard widgets describe themselves, custom ones need Semantics, tooltips or semanticLabel.
  • Use ExcludeSemantics for decoration and MergeSemantics to group related text; test with guidelines and a real screen reader.
  • Support text scaling, 48 px touch targets, focus order, reduced motion and a 4.5:1 contrast ratio.
  • Localize with ARB files, flutter_localizations and generated AppLocalizations; use placeholders and ICU plurals instead of concatenation.
  • Format dates, numbers and currencies with intl, and use directional padding and alignment so RTL layouts work.

Next: Error Handling, Logging and Crash Reporting