1
---
2
name: i18n-change-workflow
3
description: Reusable i18n workflow for coding agents. Verifies locale completeness, hardcoded text, placeholders, pluralization, fallback behavior, formatting, translation consistency, and localization-related UI regressions.
4
---
5
6
# i18n Change Workflow
7
8
Act as the i18n/l10n specialist layer for the active task.
9
10
This skill adds localization-specific constraints and verification. It does not replace the repository's normal implementation, audit, Git, or approval workflow. Follow the active workflow's mutation boundary: during implementation or remediation, apply the required i18n changes; during a read-only audit or review, use these criteria without modifying repository state.
11
12
## 1. Inspect the existing i18n system first
13
14
Before changing localized behavior:
15
16
- read applicable `AGENTS.md` and project documentation;
17
- identify the current i18n library or project-native mechanism;
18
- identify supported locales, source/default locale, locale resource locations, fallback behavior, and locale-selection/persistence logic;
19
- inspect nearby existing keys and call sites before choosing new key names or structures;
20
- identify project-specific rules for translations, formatting, generated resources, or validation.
21
22
Prefer the existing project architecture. Do not introduce a new i18n library, resource format, or parallel translation mechanism unless the task requires it and the repository has no suitable existing mechanism.
23
24
Do not treat one framework convention as universal. Follow the repository's actual conventions.
25
26
## 2. Classify text before localizing it
27
28
Determine whether each changed string is actually user-facing.
29
30
Typical localization candidates include:
31
32
- visible UI labels, buttons, headings, menus, dialogs, empty states, validation messages, and user-visible errors;
33
- accessibility labels and descriptions;
34
- notifications and user-facing system messages;
35
- placeholders, helper text, onboarding copy, and tooltips;
36
- user-visible content generated from application-owned templates.
37
38
Do not automatically localize:
39
40
- identifiers, translation keys, API names, URLs, paths, commands, SQL, regexes, or protocol values;
41
- developer-only logs, diagnostics, stack traces, and test fixture text;
42
- brand names, product names, codes, or terms that project rules intentionally preserve;
43
- externally supplied runtime content unless the task explicitly covers it.
44
45
When classification is ambiguous and affects product meaning, preserve the current behavior and surface the ambiguity rather than guessing.
46
47
## 3. Preserve the project's key and resource model
48
49
For new or changed user-facing text:
50
51
- use the project's translation mechanism instead of introducing hardcoded display text when localization is expected;
52
- follow the existing key naming and namespacing convention;
53
- prefer stable semantic keys over keys derived from full display sentences unless the project intentionally uses source-text keys;
54
- update every supported locale required by project rules or the current task;
55
- preserve unrelated locale entries and target-only data unless deletion is explicitly intended;
56
- do not silently rename or delete existing keys merely for stylistic consistency.
57
58
Treat the project's declared source/default locale as canonical only if the repository actually uses that model.
59
60
Missing translations must follow the project's established fallback policy. Do not invent a new fallback policy silently.
61
62
## 4. Preserve interpolation, pluralization, and message structure
63
64
Translation structure is part of the contract.
65
66
- Preserve the same required placeholders/arguments across locale variants.
67
- Do not translate placeholder names, format tokens, markup, or control syntax.
68
- Use the project's plural/select/ICU mechanism when grammar depends on count, gender, case, or other locale-sensitive variation.
69
- Avoid assembling sentences from separately translated fragments when word order or grammar can vary by language.
70
- Avoid string concatenation that assumes English word order or spacing.
71
- Preserve intentional markup, escaping, and line-break semantics.
72
73
If a source message changes its arguments or message structure, verify every affected locale rather than updating only the visible source text.
74
75
## 5. Keep locale-sensitive values locale-aware
76
77
When the changed UI contains locale-sensitive values, use the project's existing locale-aware formatting facilities for relevant:
78
79
- dates and times;
80
- numbers and percentages;
81
- currencies;
82
- units;
83
- relative time;
84
- list formatting;
85
- plural categories.
86
87
Do not hardcode separators, decimal conventions, date ordering, currency placement, or English-only plural assumptions when locale-aware behavior is expected.
88
89
## 6. Protect locale selection and fallback behavior
90
91
When the task touches locale switching, initialization, persistence, or fallback:
92
93
- preserve the project's supported-locale list and normalization rules;
94
- verify default-locale behavior;
95
- verify persistence if the project stores the user's language choice;
96
- verify unsupported or missing locales degrade through the intended fallback path;
97
- avoid mixed-language UI caused by missing keys or stale cached locale data;
98
- ensure lazy-loaded locale resources are awaited or synchronized correctly when applicable.
99
100
Do not change locale-detection precedence without an explicit requirement.
101
102
## 7. Translation quality
103
104
When generating or editing translations:
105
106
- preserve meaning, intent, tone, and product terminology rather than translating mechanically word-for-word;
107
- use surrounding UI context to resolve ambiguous short labels;
108
- preserve approved product names, technical terms, and glossary decisions;
109
- keep placeholders and markup intact;
110
- avoid adding claims, meaning, politeness level, or functionality not present in the source;
111
- flag uncertain, culturally sensitive, legal, safety-critical, or brand-sensitive wording for human confirmation instead of pretending certainty.
112
113
If the repository contains a glossary, terminology file, translation memory, or established translations, prefer that evidence over a newly generated alternative.
114
115
Read `references/i18n-review-checklist.md` when doing a broad locale addition, translation review, or release-oriented localization change.
116
117
## 8. Check UI and layout risk
118
119
Localized text can change layout even when the translation is correct.
120
121
For affected UI, consider when relevant:
122
123
- longer labels and multi-line wrapping;
124
- narrow mobile widths and responsive layouts;
125
- CJK line breaking and glyph coverage;
126
- text truncation and ellipsis;
127
- buttons, tabs, badges, dialogs, tables, and fixed-width containers;
128
- font fallback;
129
- accessibility labels;
130
- right-to-left direction, mirroring, and logical CSS/layout properties when an RTL locale is in scope.
131
132
Do not add RTL-specific work when no RTL locale is supported or requested, but do not ignore it when an RTL locale is part of the task.
133
134
Use visual or UI verification when the changed text can plausibly affect layout. A successful locale-file check alone does not prove the UI is correct.
135
136
## 9. Verify with project-native checks
137
138
Use the repository's existing i18n validators, tests, linters, builds, and UI checks first.
139
140
Verify the relevant subset of:
141
142
- locale-key completeness/parity;
143
- missing or blank translations;
144
- placeholder/argument parity;
145
- plural/select structure;
146
- fallback behavior;
147
- locale switching and persistence;
148
- locale-aware formatting;
149
- absence of newly introduced hardcoded user-facing strings in the changed scope;
150
- build/type/lint/test health;
151
- layout behavior for affected screens.
152
153
For plain JSON locale catalogs, `scripts/check_json_locales.py` may be used as an additional deterministic check. It checks duplicate JSON keys, key parity, value types, blank strings, and common brace-style named placeholder/ICU argument parity. Placeholder detection is intentionally narrow and heuristic; confirm reported mismatches against the project's actual message syntax. It is not a semantic translation review and does not replace project-native tooling.
154
155
Do not claim repository-wide i18n completeness from a narrow file or static check.
156
157
## 10. Completion criteria
158
159
An i18n change is complete only when, for the requested scope:
160
161
- the intended user-facing strings use the project's localization mechanism;
162
- required locale resources are updated;
163
- placeholders and message structure remain compatible;
164
- relevant formatting/fallback/switching behavior is preserved;
165
- project-native verification passes, or limitations are explicitly reported;
166
- plausible layout regressions have been checked when the UI is affected;
167
- unresolved translation or product-language ambiguity is reported rather than guessed.
168
169
Keep the final report concise. State what locale behavior changed, which locales/resources were touched, what validation actually ran, and any remaining translation or UI limitations.
170