Skip to main content

prefer-localized-semantic-labels

v1.39.0
warning
effort: 8m
configurable
pro+

Warns when a string literal is passed to accessibility-related parameters (label:, tooltip:, semanticLabel:, etc.).

By default checks only standard Flutter widgets (icons, images, buttons, progress indicators and Semantics).

Modern mobile apps support multiple locales and languages. When developers hardcode string literals for accessibility properties (e.g., Semantics(label: 'Close dialog') or IconButton(tooltip: 'Delete')), non-English users using localized interfaces will hear accessibility labels read out in English.

Furthermore, screen reader text-to-speech engines assigned to foreign languages (e.g. Polish or Spanish) will attempt to pronounce English words phonetically, producing unintelligible, distorted voice output for blind users.

⚙️ Config​

Set additional-widgets (default is empty) to add additional widgets to the list of checked widgets.

Set allowed-literals (default is empty) to exclude configured literals.

Set ignore-identifiers (default is true) to allow passing widget fields and variables (setting to false will highligh any passed identifier)

analysis_options.yaml
dcm:
  rules:
    - prefer-localized-semantic-labels:
        additional-widgets:
          - CustomButton: title
          - CustomSwitch: customLabel
        allowed-literals:
          - Cancel
          - OK
        ignore-identifiers: true

Example​

❌ Bad:

// LINT: Provide a localized semantic label.
Semantics(label: '');

// LINT: Provide a localized semantic label.
Semantics(label: 'Cancel');

✅ Good:

Semantics(label: someString); // will be highlighted if `ignore-identifiers` is `false`
Semantics(label: context.l10n.value);
Semantics(label: AppLocalizations.of(context).label);

Additional Resources​

Last updated on