You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: .agents/skills/i18n-development/SKILL.md
+99Lines changed: 99 additions & 0 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -175,3 +175,102 @@ All i18n changes have negligible performance impact:
175
175
3.**LLM output is a soft constraint**: Language instructions guide the LLM but cannot guarantee compliance. Most models follow reliably.
176
176
4.**`TranslationKey` type**: Must match keys in all `en/*.json` files. Auto-derived via `import type` + `keyof typeof`.
177
177
5.**Tool docs**: `templates/tools/*.md` stay in English (sent to LLM, not user-facing).
178
+
179
+
## Common Pitfalls
180
+
181
+
### 1. 🚫 Module-Level `t()` Calls (i18n Not Yet Initialized)
182
+
183
+
**Problem**: `t()` called at module scope evaluates BEFORE `initI18n()` runs (ESM import resolution order). The translation cache is empty, so `t()` returns the key string itself.
**Rule**: React components → `const { t } = useI18n()`. Non-React modules → `import { t } from "../common/i18n"`. Never both in the same file.
221
+
222
+
### 4. 🚫 Ink `useInput` Event Propagation Without Guards
223
+
224
+
**Problem**: Ink delivers keyboard events to ALL active `useInput` hooks. When a dropdown is open, Enter triggers both the dropdown's action AND the parent's submit.
225
+
226
+
```typescript
227
+
// ❌ WRONG — showConfigDropdown missing
228
+
if (openRawModelDropdown||showSkillsDropdown||showModelDropdown) { return; }
229
+
submitCurrentBuffer(); // fires while ConfigDropdown is open!
230
+
```
231
+
232
+
**Fix**: Include ALL dropdown states in the guard:
233
+
234
+
```typescript
235
+
// ✅ CORRECT
236
+
if (openRawModelDropdown||showSkillsDropdown||showModelDropdown||showConfigDropdown) { return; }
237
+
```
238
+
239
+
### 5. 🚫 Test Fixtures Without `initI18n`
240
+
241
+
Tests calling functions using `t()` must call `initI18n("en")` first, otherwise `t()` returns key strings.
242
+
243
+
### 6. 🚫 Translation Key Naming Mismatch
244
+
245
+
Run `npm run check:i18n` before PR. Also audit key usage:
0 commit comments