I18n Naming

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; also serves HK users via Chrome's zh_TW → zh → default fallback chain when no zh_HK is present — we do not ship a separate zh_HK)

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.

errors:
  # $1 = file name, $2 = size limit
  fileTooLarge: "$1 exceeds $2 limit"

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:

# 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:

chat:
  history:
    # $1 = count
    count:
      0: "No messages"
      1: "1 message"
      n: "$1 messages"

Call with the count as the second argument:

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:

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:

# 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"

// 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.

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.