| name | add-translation |
| description | Use this skill when adding or changing a user-visible string — including requests like "change this label", "add a message for X", "translate the button", "добавь строку", "поменяй текст на экране". The project localizes through gen-l10n with three ARB locales (en/ru/kk); a hardcoded string literal in a widget is a defect. Covers ARB key placement, ICU plurals/placeholders, regeneration, and the untranslated-messages check. |
Add a Localized String
Every user-visible string lives in the ARB files and is read via L10n.current.<key>. Dev-only labels are the single exception.
Steps
- Add the key to the template file
lib/src/core/l10n/translations/intl_en.arb, then mirror it in intl_ru.arb and intl_kk.arb. Keys are camelCase and describe meaning (changeTheme), not presentation.
- For dynamic content use placeholders with
@key metadata; for plurals use ICU select/plural syntax in the ARB — branching on count in Dart is a bug.
- Regenerate:
fvm flutter gen-l10n (a full build_runner build also triggers it). Output lands in lib/src/core/l10n/generated/app_localizations.g.dart.
- Read the string in widgets as
L10n.current.<key> (see settings feature for usage).
- Confirm
untranslated_messages.txt is empty — a non-empty file means a locale is missing the key.
Gotchas
- English (
intl_en.arb) is the template — a key added only to ru/kk does not generate a getter.
nullable-getter: false is set, so a key missing from the template breaks the build rather than returning null; treat generator errors as a missing-key signal.- Kazakh (
kk) is easy to forget; the missing translation only surfaces in untranslated_messages.txt, not as a compile error.
- Compose dynamic text via placeholders, never by concatenating localized fragments — word order differs across en/ru/kk.
