home / skills / yelmuratoff / agent_sync / localization

localization skill

safe

This skill helps you implement Flutter localization with gen-l10n by configuring arb keys, plural rules, and wiring strings into widgets.

npx playbooks add skill yelmuratoff/agent_sync --skill localization

Review the files below or copy the command above to add this skill to your agents.

Files (1)

SKILL.md

1.8 KB

---
name: localization
description: When adding Flutter localizations (gen-l10n), ARB keys, parameters, and pluralization, and wiring localized strings into widgets.
---

# Localization (gen-l10n / intl)

## When to use

- Adding a new screen/feature with user-visible strings.
- Introducing parameters or pluralization.
- Replacing hardcoded strings with localized strings.

## Steps

### 1) Enable Flutter localization generation

Add a `l10n.yaml` (or use your existing config) and ensure Flutter gen-l10n is enabled.

Example `l10n.yaml`:

```yaml
arb-dir: lib/l10n
template-arb-file: app_en.arb
output-localization-file: app_localizations.dart
output-class: AppLocalizations
```

### 2) Add ARB keys (stable and descriptive)

Example `lib/l10n/app_en.arb`:

```json
{
  "@@locale": "en",
  "ordersTitle": "Orders",
  "ordersCount": "{count, plural, =0{No orders} =1{1 order} other{{count} orders}}",
  "@ordersCount": {
    "description": "Shown on the orders screen",
    "placeholders": { "count": { "type": "int" } }
  }
}
```

Avoid concatenation; use placeholders and plural rules.

### 3) Use generated localizations in widgets

```dart
import 'package:flutter/widgets.dart';

Widget build(BuildContext context) {
  final l10n = AppLocalizations.of(context)!;
  return Text(l10n.ordersTitle);
}
```

### 4) Test critical localization-driven logic

If UI logic depends on localized output (rare), test with a fixed locale and golden/widget tests.

### 5) Support directionality (RTL/LTR)

Use directional widgets and values when layout should mirror by locale:

- `EdgeInsetsDirectional` instead of fixed left/right paddings
- `AlignmentDirectional` and `PositionedDirectional` for mirrored layouts
- `matchTextDirection: true` for icons/images that should mirror in RTL

Validate at least one critical screen in an RTL locale.

Overview

This skill guides adding Flutter localizations using gen-l10n and ARB files, covering keys, parameters, pluralization, and wiring generated strings into widgets. It focuses on practical configuration, ARB authoring patterns, using the generated AppLocalizations, and handling directionality for RTL locales. The goal is predictable, testable localized UI behavior across languages.

How this skill works

Enable Flutter's gen-l10n via a l10n.yaml and place ARB files in the configured directory. Add stable, descriptive ARB keys with placeholders and ICU plural syntax where needed. Use the generated AppLocalizations class inside widgets to retrieve localized strings, and prefer directional widgets and mirroring options to support RTL layouts. Test locale-dependent logic and at least one critical screen in an RTL locale.

When to use it

When adding a new screen or feature that shows user-visible text.
When replacing hardcoded strings with maintainable localized resources.
When introducing parameters, placeholders, or plural forms in copy.
When supporting additional locales or preparing for RTL languages.
When you need consistent programmatic access to localized strings in widgets.

Best practices

Keep ARB keys stable and descriptive; avoid concatenating strings in code.
Use ICU plural and placeholder syntax in ARB files to handle counts and parameters.
Store ARB files under lib/l10n and configure l10n.yaml to generate AppLocalizations.
Access strings via AppLocalizations.of(context) and pass typed parameters from code.
Prefer EdgeInsetsDirectional, AlignmentDirectional, and matchTextDirection for RTL support.
Add targeted widget or golden tests for any UI logic that depends on localized output.

Example use cases

Add a new screen: create app_en.arb entries, regenerate localizations, and call AppLocalizations in the screen widget.
Introduce pluralized labels: add a plural ARB entry with placeholders and use the generated method with count.
Replace concatenated labels: combine template text and placeholders in ARB to preserve grammar across languages.
Enable RTL layout: switch paddings and alignments to directional variants and validate the screen in an RTL locale.
Test localized UI: run widget tests with a fixed Locale and verify rendered strings and layout direction.

FAQ

How do I enable gen-l10n?

Add a l10n.yaml in your project root pointing to the ARB dir and template file, then run Flutter build or rely on IDE build actions to generate AppLocalizations.

How should I handle pluralization and parameters?

Use ICU plural syntax in ARB entries and declare placeholders with types; the generator produces methods that accept typed parameters like count or name.