maotoumao/Cebian / .agents/skills/i18n-naming
i18n-naming
VerifiedCebian project i18n key naming, placeholder, pluralization, file layout, and glossary conventions. MUST be used whenever adding, editing, refactoring, or reviewing any translation key in `locales/*.yml`, any `t(...)` call in source code, or any `__MSG_*__` placeholder in manifest. Also triggers when reviewing diffs that touch i18n files, when proposing new user-facing strings, or when validating translation completeness/consistency between `en.yml`, `zh_CN.yml`, and `zh_TW.yml`.
| File | Kind | Size |
|---|---|---|
| SKILL.md | skill md | 16.2 KB |
| agents/openai.yaml | config | 192 B |
SKILL.md
View on GitHub---
name: i18n-naming
description: Cebian project i18n key naming, placeholder, pluralization, file layout, and glossary conventions. MUST be used whenever adding, editing, refactoring, or reviewing any translation key in `locales/*.yml`, any `t(...)` call in source code, or any `__MSG_*__` placeholder in manifest. Also triggers when reviewing diffs that touch i18n files, when proposing new user-facing strings, or when validating translation completeness/consistency between `en.yml`, `zh_CN.yml`, and `zh_TW.yml`.
---
# Cebian i18n Naming & Convention Skill
This skill captures the agreed-upon rules for the Cebian extension's i18n
implementation, built on `@wxt-dev/i18n` with its simple YAML format. All
translation work — both authoring and review — must follow these rules.
## When to apply
- Adding any new `t('...')` call in source.
- Editing any of `locales/en.yml`, `locales/zh_CN.yml`, or `locales/zh_TW.yml`.
- Reviewing a diff that touches i18n.
- Validating that a translation set is complete & consistent.
- Adding a manifest-level localized string (`__MSG_*__`).
## Languages & file layout
Cebian ships **three independently maintained** locales:
- `en` — default (fallback for all non-Chinese users)
- `zh_CN` — Simplified Chinese (Mainland conventions)
- `zh_TW` — Traditional Chinese (Taiwan conventions). We do not ship a
separate `zh_HK`; which bundle a zh-HK browser gets is up to the browser's
own fallback rules and is not guaranteed to be `zh_TW`. Hong Kong / Macau
users can pick 繁體中文 explicitly in Settings → Appearance → Language.
Source files live at:
```
locales/en.yml
locales/zh_CN.yml
locales/zh_TW.yml
```
All three are **hand-authored** and must respect each language's idiomatic
style. `zh_TW` is NOT a mechanical character conversion of `zh_CN`; word
choice differs (see the Traditional Chinese glossary below).
The WXT module compiles them into
`.output/<browser>/_locales/{en,zh_CN,zh_TW}/messages.json` at build
time. Never edit generated `messages.json` files by hand. Chrome's
`_locales/` directory does not accept a bare `zh` folder, which is why
we ship `zh_CN` and `zh_TW` separately.
## Key naming rules
### Namespace hierarchy
Use a fixed top-level namespace set. Do not invent new top-level namespaces
without updating this skill first.
```
common # generic verbs/labels reused across UI (send, cancel, save, ...)
chat # /chat/* page (input, message, tools)
settings # /settings/* page (layout, providers, chat, prompts, skills, data, about)
provider # provider sub-components (oauth, apiKey, custom)
tools # agent tool runtime labels (shown in ToolCard while a tool runs)
vfs # standalone VFS browser entrypoint (entrypoints/vfs)
permission # standalone user-permission entrypoint (entrypoints/user-permission)
dialogs # modal dialogs
errors # toast / inline error messages
agent # agent-runtime user-facing strings
pageActions # in-page injected UI (floating ball, selection toolbar)
# Flat top-level keys (manifest exception, see "Manifest localization"):
# extName, extDescription, actionTitle
```
### Key syntax
- Dot-separated path: `namespace.block.name` (e.g. `chat.input.placeholder`).
- Each segment is **lowerCamelCase**: `apiKey` not `api-key`, not `api_key`.
- Final segment names the *thing*, not the *element type*.
- Good: `common.cancel`, `errors.fileTooLarge`
- Bad: `common.cancelButton`, `errors.fileTooLargeMessage`
- Action labels use a verb: `common.send`, `common.delete`.
- Status labels use an adjective/past participle: `provider.oauth.loggedIn`.
- Errors live under `errors.*` and read as a sentence.
### Reuse vs duplication
Prefer **one canonical key per concept**, reused across the UI, over
near-duplicates. Every "Cancel" button must use `common.cancel`. Add a
non-`common` key only when the wording legitimately differs in context.
## Placeholders
`@wxt-dev/i18n`'s simple YAML format only supports **positional**
substitutions `$1`–`$9`. Named placeholders (`$NAME$`) are only available
via the verbose Chrome `messages.json` format, which we do not use.
### Rules
- Use `$1`, `$2`, ... `$9` in message text.
- Document the meaning of each `$N` with an inline YAML comment **on the
line above the message**, so translators see what they are.
- Pass substitutions as an array literal at the call site, in the **same
order** as the comment documents.
```yaml
errors:
# $1 = file name, $2 = size limit
fileTooLarge: "$1 exceeds $2 limit"
```
```ts
t('errors.fileTooLarge', [file.name, '5MB']);
```
### Escaping
To produce a literal `$`, double it: `$$`.
### Word-order differences across locales
If natural sentence order differs between en and zh, **keep the indices
the same and rearrange the surrounding text**:
```yaml
# en.yml — $1 = model, $2 = provider
chat.modelLine: "Using $1 from $2"
# zh.yml — same indices, different surrounding text
chat.modelLine: "正在使用 $2 的 $1"
```
The call site `t('chat.modelLine', [model, provider])` works for both.
### Forbidden in placeholder values
- HTML or markdown — placeholders interpolate as plain text.
- Nested translation calls — compose at the call site instead.
## Pluralization
`@wxt-dev/i18n` plural syntax (NOT i18next's `_one`/`_other` suffixes).
A pluralized key is a map with numeric keys plus `n`:
```yaml
chat:
history:
# $1 = count
count:
0: "No messages"
1: "1 message"
n: "$1 messages"
```
Call with the count as the **second argument**:
```ts
t('chat.history.count', 0); // "No messages"
t('chat.history.count', 1); // "1 message"
t('chat.history.count', 5); // "5 messages"
```
Chinese has no plural form, but **must still provide the same shape** so
the key set is symmetric:
```yaml
chat:
history:
count:
0: "暂无消息"
1: "1 条消息"
n: "$1 条消息"
```
## Manifest localization
For `manifest.json` fields use `__MSG_<key>__` placeholders. **Chrome
restricts the key to `[a-zA-Z0-9_]`** — dots are not allowed inside the
placeholder. Therefore manifest keys are an **exception to the
namespace rule** and live as flat top-level entries in the YAML files:
```yaml
# en.yml
extName: "Cebian"
extDescription: "AI-powered browser sidebar assistant"
actionTitle: "Open Cebian sidebar"
# (all other keys remain nested under their namespace)
common:
newChat: "New chat"
```
```ts
// wxt.config.ts
manifest: {
default_locale: 'en',
name: '__MSG_extName__',
description: '__MSG_extDescription__',
action: { default_title: '__MSG_actionTitle__' },
}
```
The allow-list of flat top-level keys is fixed:
`extName`, `extDescription`, `actionTitle`. Adding a new flat key
requires updating this skill.
## Runtime language switching
Users can override the browser language in Settings → Appearance (issue #50).
`t` from `@/lib/i18n` then reads `_locales/<locale>/messages.json` as an
override dictionary instead of `chrome.i18n.getMessage`. Consequences for
locale authors:
- **`$` usage is limited** to single-digit `$1`–`$9` and a standalone `$$`.
The runtime formatter (`lib/i18n/format.ts`) reproduces only these, and
Chrome-style `placeholders` blocks are not supported. `scripts/lint-i18n.mjs`
enforces this.
- **`common.languageTag`** is metadata, not display text: each file declares
its own BCP-47 tag (`en` / `zh-CN` / `zh-TW`). The runtime reads it to set
`<html lang>` to the language actually rendered. Never translate it.
- **Language names** under `settings.appearance.language.{en,zhCN,zhTW}` are
endonyms and stay identical in every locale file.
- **Adding a locale** also means adding it to `UI_LOCALES` / `LANGUAGE_TAGS`
in `lib/i18n/locales.ts` (a test checks `UI_LOCALES` against
`locales/*.yml`) and to `LANGUAGE_LABELS` in
`components/settings/sections/AppearanceSection.tsx`, plus its own
`common.languageTag` and endonym key.
## Glossary (canonical translations)
Authoritative. Any deviation must be discussed and added here. The
`zh_TW` column is **not a character-conversion** of `zh_CN` — Taiwan
usage frequently picks a different word entirely.
| EN | 简体中文 (zh_CN) | 繁體中文 (zh_TW) | Notes |
| ----------------- | ---------------- | ---------------- | ---------------------------------- |
| Cebian | Cebian | Cebian | Brand name, never translated |
| Extension | 扩展 | 擴充功能 | TW prefers 擴充功能 over 擴充/擴展 |
| Provider | 提供商 | 供應商 | TW commonly uses 供應商 |
| Model | 模型 | 模型 | |
| Skill | 技能 | 技能 | Translated |
| Prompt | 提示词 | 提示詞 | Translated |
| Agent | 智能体 | 智慧型代理 | TW: 智慧型代理 (avoid bare 代理) |
| Tool | 工具 | 工具 | |
| Session / Chat | 会话 / 对话 | 工作階段 / 對話 | TW: 工作階段 for technical session |
| Thinking | 思考 | 思考 | |
| Settings | 设置 | 設定 | TW: 設定 (not 設置) |
| Sidepanel | 侧边栏 | 側邊欄 | |
| Token | Token | Token | Keep English |
| API Key | API Key | API Key | Keep English |
| OAuth | OAuth | OAuth | Keep English |
| Sign in / Login | 登录 | 登入 | TW: 登入 (not 登錄) |
| Sign out / Logout | 退出 | 登出 | TW: 登出 |
| Verify | 验证 | 驗證 | |
| Archive (verb) | 归档 | 封存 | TW: 封存 (not 歸檔) |
| Save | 保存 | 儲存 | TW: 儲存 (not 保存) |
| Cancel | 取消 | 取消 | |
| Delete | 删除 | 刪除 | |
| Confirm | 确认 | 確認 | |
| Send | 发送 | 傳送 | TW: 傳送 (not 發送) |
| Open | 打开 | 開啟 | TW: 開啟 (not 打開) |
| Close | 关闭 | 關閉 | |
| New chat | 新对话 | 新對話 | |
| History | 历史 / 历史记录 | 歷史 / 歷史記錄 | Use longer form as panel title |
| Search | 搜索 | 搜尋 | TW: 搜尋 (not 搜索) |
| File | 文件 | 檔案 | TW: 檔案 (not 文件) |
| Folder | 文件夹 | 資料夾 | TW: 資料夾 |
| Network | 网络 | 網路 | TW: 網路 (not 網絡) |
| Default | 默认 | 預設 | TW: 預設 (not 默認) |
| Information | 信息 | 資訊 | TW: 資訊 (not 訊息/信息) |
| Program / Software| 程序 / 软件 | 程式 / 軟體 | TW: 程式, 軟體 |
| Data | 数据 | 資料 | TW: 資料 (not 數據) |
## Style rules
- **Buttons / menu items**: imperative verb phrase, no trailing punctuation.
- en: `Send`, `Open in new tab`
- zh_CN: `发送`、`在新标签页打开`
- zh_TW: `傳送`、`在新分頁開啟`
- **Tooltips / aria-label**: same as button text unless it adds info.
- **Toasts**:
- Success: short statement, no exclamation. en: `Saved` / zh_CN: `已保存` / zh_TW: `已儲存`
- Error: state what failed and (when actionable) why.
- **Placeholders / empty states**: hint, not instruction.
- en: `Search models…` zh_CN: `搜索模型…` zh_TW: `搜尋模型…`
- **Sentence punctuation**:
- en: ASCII punctuation (`. , ! ? : ;`).
- zh_CN / zh_TW: full-width Chinese punctuation (`。,!?:;`).
- Ellipsis: single character `…` for all locales, **never** `...`.
- **Length budget**: a zh string used inside a button or badge should not
exceed the en string by more than ~30% in rendered width.
- **Capitalization (en)**: sentence case for body text and tooltips,
Title Case only for proper nouns and section headings.
## Authoring workflow
1. Add the key to `locales/en.yml` first.
2. Add the same key to `locales/zh_CN.yml` (Simplified, Mainland style).
3. Add the same key to `locales/zh_TW.yml` (Traditional, Taiwan style).
This is NOT a character conversion of `zh_CN` — use Taiwan-idiomatic
word choices per the Traditional Chinese glossary below.
4. Update the call site to `t('your.key')` (or `t('your.key', [arg1, ...])`).
5. If using positional placeholders, document the meaning of each `$N`
with an inline YAML comment on the preceding line, in all three locales.
6. Run `pnpm check` (compiles types and runs the i18n lint).
## Review checklist
Run through this list explicitly when reviewing any i18n-touching diff.
Cite each item as pass/fail.
1. **Key parity**: every key in `en.yml`, `zh_CN.yml`, and `zh_TW.yml`
matches the same set. No orphans in any locale.
2. **Placeholder index parity**: for every key, the set of `$N` indices
in en, zh_CN, and zh_TW is **identical** (same numeric set, same
count). The surrounding text may differ for word order.
3. **Pluralization parity**: any plural key (with `0`/`1`/`n` subkeys)
has the same subkey set in all three languages.
4. **Namespace conformance**: every new key sits under one of the
approved top-level namespaces.
5. **Naming conformance**: every segment is lowerCamelCase; final segment
names the *thing*, not the element type.
6. **Glossary conformance**: every glossary term in en is rendered with
the canonical zh translation. Flag deviations.
7. **Style conformance**: buttons are verb phrases; zh punctuation is
full-width; ellipsis is `…`; no trailing punctuation in button labels.
8. **Placeholder doc comment present** for every key with `$N`, in both
locales.
9. **No HTML / markdown / interpolated keys** in message strings.
10. **Reuse check**: does an existing `common.*` key already cover this?
If yes, prefer reusing.
11. **Length sanity**: zh strings used in tight UI (buttons, badges,
tabs) are not dramatically longer than their en counterparts.
12. **Back-translation spot-check**: pick ~10% of new zh keys and
silently back-translate to en; flag any that drift in meaning.
Output the review as a structured report:
```
## i18n review
Pass: <count>
Fail: <count>
Notes: <count>
### Failures
- <key>: <reason> -> <suggested fix>
### Notes (non-blocking)
- <key>: <observation>
```
## Anti-patterns (never do)
- Hard-coding zh in `.tsx` "just for this one toast".
- Inventing a new top-level namespace without updating this skill.
- Translating brand names, code identifiers, file paths, or HTTP method
names.
- Embedding line breaks inside a translation string for layout. Use
separate keys or component composition instead.
- Concatenating translated fragments in code (`t('a') + ' ' + t('b')`).
Make one key with placeholders.
## Migration-friendliness reminder
These conventions exist so a future move to `react-i18next` is mechanical:
- positional `$1` `$2` → i18next `{{0}}` `{{1}}` (or named via codemod)
- `0`/`1`/`n` plural maps → i18next `_zero` / `_one` / `_other` suffixes
- nested dot keys → nested JSON (already shaped)
- `t('key', [...])` → `t('key', [...])` (codemod-friendly)
Do not introduce features that break this property without explicit
project-level approval.
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| receiving-code-reviewobra/superpowersUse when receiving code review feedback, before implementing suggestions, especially if feedback seems unclear or technically questionable - requires technical rigor and verification, not performative agreement or blind implementation | Stars: 323k | Updated | Claude CodeCodex | Verified | Install |
| requesting-code-reviewobra/superpowersUse when completing tasks, implementing major features, or before merging to verify work meets requirements | Stars: 323k | Updated | Claude CodeCodex | Verified | Install |
| using-git-worktreesobra/superpowersUse when starting feature work that needs isolation from current workspace or before executing implementation plans - ensures an isolated workspace exists via native tools or git worktree fallback | Stars: 323k | Updated | Claude CodeCodex | Verified | Install |
| verification-before-completionobra/superpowersUse when about to claim work is complete, fixed, or passing, before committing or creating PRs - requires running verification commands and confirming output before making any success claims; evidence before assertions always | Stars: 323k | Updated | Claude CodeCodex | Verified | Install |