From 94f2fd9420f05e2adc9e7f8a988c81df405238f3 Mon Sep 17 00:00:00 2001 From: Naiyuan Qing <145280634+NevilleQingNY@users.noreply.github.com> Date: Wed, 6 May 2026 15:08:23 +0800 Subject: [PATCH] docs(conventions): consolidate naming + i18n glossary into docs site MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Single source of truth for code naming, i18n translation glossary, and Chinese voice rules. Previously split between packages/views/locales/glossary.md and scattered comments — now lives at apps/docs/content/docs/developers/conventions.{mdx,zh.mdx} with both English and Chinese versions kept in sync. Three sections per page: 1. Code naming — routes, packages, files, DB, Go, TS, commits 2. i18n translation glossary — entity vs concept rule, what to translate, word combination, plurals, interpolation, key naming 3. Chinese voice + style — punctuation, principles, where to look in doubt Side effects: - packages/views/locales/glossary.md collapses to a stub redirecting to the docs page; do not edit it - CLAUDE.md gets a new top-level "Conventions reference" section so any Claude session sees the pointer before any other rule - apps/docs/content/docs/developers/ gets a stub English meta.json so the conventions page is reachable on the EN side (contributing.zh.mdx / architecture.zh.mdx remain ZH-only — separate work) - Both root sidebars get a new "Developers" group Co-Authored-By: Claude Opus 4.7 (1M context) --- CLAUDE.md | 15 + .../content/docs/developers/conventions.mdx | 285 ++++++++++++++++++ .../docs/developers/conventions.zh.mdx | 285 ++++++++++++++++++ apps/docs/content/docs/developers/meta.json | 4 + .../docs/content/docs/developers/meta.zh.json | 2 +- apps/docs/content/docs/meta.json | 4 +- apps/docs/content/docs/meta.zh.json | 4 +- packages/views/locales/glossary.md | 213 +------------ 8 files changed, 604 insertions(+), 208 deletions(-) create mode 100644 apps/docs/content/docs/developers/conventions.mdx create mode 100644 apps/docs/content/docs/developers/conventions.zh.mdx create mode 100644 apps/docs/content/docs/developers/meta.json diff --git a/CLAUDE.md b/CLAUDE.md index 1718a86701..c2669747b3 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -2,6 +2,21 @@ This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository. +## Conventions reference + +The single source of truth for **code naming, the i18n translation glossary, and the Chinese voice guide** is the docs site: + +- **`apps/docs/content/docs/developers/conventions.mdx`** (English) +- **`apps/docs/content/docs/developers/conventions.zh.mdx`** (Chinese) + +Read that page before: + +- Writing or editing translations (`packages/views/locales/`) +- Naming a new route, package, file, DB column, or TS type +- Writing Chinese product copy (UI strings, error messages, docs) + +The legacy `packages/views/locales/glossary.md` is now a stub redirecting to the docs page; do not rely on it. + ## Project Context Multica is an AI-native task management platform — like Linear, but with AI agents as first-class citizens. diff --git a/apps/docs/content/docs/developers/conventions.mdx b/apps/docs/content/docs/developers/conventions.mdx new file mode 100644 index 0000000000..97580a5d2c --- /dev/null +++ b/apps/docs/content/docs/developers/conventions.mdx @@ -0,0 +1,285 @@ +--- +title: Conventions +description: Single source of truth for code naming, i18n translation glossary, and Chinese voice guide. +--- + +This page is the single source of truth for code naming, the i18n translation glossary, and the Chinese voice guide. Anything that used to live in `packages/views/locales/glossary.md` or in scattered comments now lives here. + +If you write Multica code, change a translation, or write Chinese product copy, this is the page to reference. + +--- + +## 1. Code naming + +### Routes + +Pre-workspace routes (the routes that exist before the user is in a workspace) MUST use either a single word or the `/{noun}/{verb}` pattern. + +- ✅ `/login`, `/inbox`, `/workspaces/new` +- ❌ `/new-workspace`, `/create-team`, `/accept-invite` + +Hyphenated word groups at the root collide with user-chosen workspace slugs and force endless reserved-slug audits. Reserving the noun (`workspaces`) automatically protects the entire `/workspaces/*` subtree. + +### Workspace-scoped routes + +Always live under `/{slug}/{section}` — `/{slug}/issues`, `/{slug}/agents`, `/{slug}/settings`. Never duplicate workspace routing logic; use `useNavigation().push()` from shared code, never framework-specific link APIs. + +### Packages and modules + +The monorepo enforces strict package boundaries: + +| Package | May depend on | Must NOT depend on | +| --- | --- | --- | +| `packages/core` | nothing app-specific | `react-dom`, `localStorage`, `process.env`, `next/*`, UI libraries | +| `packages/ui` | nothing | `@multica/core`, business logic | +| `packages/views` | `core/`, `ui/` | `next/*`, `react-router-dom`, stores | +| `apps/web/platform/` | `next/*` | other apps | +| `apps/desktop/.../platform/` | `react-router-dom`, electron | other apps | + +If logic appears in both apps, it MUST be extracted to a shared package. There are no exceptions for "small" duplication. + +### Files and components + +- Files: `kebab-case.tsx` / `kebab-case.ts` (e.g. `agent-row-actions.tsx`) +- Components: `PascalCase` (e.g. `AgentRowActions`) +- Hooks: `useCamelCase` (e.g. `useWorkspaceId`) +- Tests: colocated as `.test.ts(x)` +- Stores (Zustand): `-store.ts`, exported as `useStore` + +### Database (Go + sqlc) + +- Tables: `snake_case` singular (`user`, `workspace`, `agent_runtime`) +- Columns: `snake_case` (`workspace_id`, `created_at`, `last_seen_at`) +- Foreign keys: `_id` +- Booleans: `is_` or `_at` (timestamp form preferred for state changes) +- Migration files: `NNN_descriptive_name.up.sql` + `.down.sql` — always provide both directions + +### Go + +- Standard `gofmt` + `go vet`. No exceptions. +- Handler files mirror domain: `agent.go`, `auth.go`, `runtime.go` +- Tests: `_test.go` colocated +- For UUID parsing in handlers, follow the rule in the root `CLAUDE.md` — `parseUUIDOrBadRequest` for boundary input, `parseUUID` (panicking) for trusted round-trips, never `util.ParseUUID` directly without checking the error. + +### TypeScript + +- API responses on the wire are `snake_case`; the api client converts to `camelCase` at the boundary. Inside TS code, **always camelCase**. +- Types: `PascalCase` (`Issue`, `AgentRuntime`); never `IPrefix`, never `_t` suffix. +- Enums: prefer string literal unions; reserve `enum` for runtime-iterable cases. +- TanStack Query keys: factory functions in `/queries.ts`, e.g. `issueKeys.detail(id)`. + +### Issue keys + +Every issue has a human-readable key like `MUL-123`: workspace `issue_prefix` (3 letters, uppercase) + sequence number. The prefix is set at workspace creation and is never changed afterward. + +### Comments in code + +English only. The repo enforces this for both Go and TypeScript. If you find a Chinese comment in code, it's a bug — replace it. + +### Commit messages + +Conventional format: `feat(scope)`, `fix(scope)`, `refactor(scope)`, `docs`, `test(scope)`, `chore(scope)`. Atomic commits grouped by intent. + +--- + +## 2. i18n translation glossary + +This is the **mandatory** glossary for every translation PR. It used to live at `packages/views/locales/glossary.md`; that file is now a stub pointing here. + +### The core distinction: entity vs concept + +Multica's product nouns split into two categories: + +- **Entity** — has a URL, a database row, an API type. In Chinese text, render as **lowercase English** so it visually reads like a type name and signals "this is a Multica system entity". +- **Concept** — generic noun, not a database entity. **Translate fully** so Chinese users don't see jagged English embedded in flowing text. + +This rule is aligned with `apps/docs/content/docs/*.zh.mdx` — the docs are the de facto Chinese voice standard and have been battle-tested across 20+ pages. + +### Don't translate — entities (lowercase English) + +| Term | Render in Chinese | Example | +| --- | --- | --- | +| Issue | `issue` (lowercase) | "把 issue 分配给智能体"、"创建子 issue" | +| Project | `project` (lowercase) | "归入某个 project" | +| Skill | `skill` (lowercase) | "为智能体注入 skill" | +| Autopilot | `autopilot` (lowercase) | "新建 autopilot" | +| Task | `task` (lowercase) | "排队中的 task" | + +### Don't translate — brands and acronyms + +| Category | Terms | +| --- | --- | +| Brands | **Multica**, GitHub, Slack, Google, Anthropic, OpenAI, Claude, Codex, Cursor, Linear, Jira | +| Acronyms | API, CLI, URL, SDK, OAuth, JWT, SSO, WebSocket, HTTP, JSON, YAML, SQL | + +### Translate fully — concepts + +| English | Chinese | +| --- | --- | +| Workspace | **工作区** | +| Agent | **智能体** | +| Daemon | **守护进程** | +| Runtime | **运行时** | +| Inbox | **收件箱** | +| Comment | **评论** | +| Reply | **回复** | +| Notifications | **通知** | +| Member | **成员** | +| Label | **标签** | +| Settings | **设置** | +| Onboarding | **上手引导** | + +### Translate fully — generic UI words + +| English | Chinese | +| --- | --- | +| Invite / Invitation | 邀请 | +| Search | 搜索 | +| Email | 邮箱 (label) / 邮件 (action) | +| Password | 密码 | +| Sign in / Log in | 登录 | +| Sign up | 注册 | +| Sign out / Log out | 退出登录 | +| Save / Cancel / Delete | 保存 / 取消 / 删除 | +| Confirm / Continue / Back | 确认 / 继续 / 返回 | +| Edit / New / Create / Add | 编辑 / 新建 / 创建 / 添加 | +| Remove / Send / Open / Close | 移除 / 发送 / 打开 / 关闭 | +| Done / Loading... | 完成 / 加载中... | +| Profile / Account / Appearance | 个人资料 / 账号 / 外观 | +| Theme / Language | 主题 / 语言 | +| Light / Dark / System | 浅色 / 深色 / 跟随系统 | +| Active / Archived | 活跃 (or 启用) / 已归档 | +| Status / Priority | 状态 / 优先级 | +| Assignee / Reporter | 负责人 / 报告人 | +| Description / Title | 描述 / 标题 | +| Date / Time | 日期 / 时间 | +| Today / Yesterday / Tomorrow | 今天 / 昨天 / 明天 | +| Empty / Failed / Success | 空 / 失败 / 成功 | +| Error / Warning | 错误 / 警告 | + +### Roles and status enums (lowercase English, not translated) + +These are schema-level identifiers; render as lowercase English even in Chinese context. + +- Roles: `owner` / `admin` / `member` +- Issue status: `backlog` / `todo` / `in_progress` / `in_review` / `done` / `blocked` / `cancelled` + +In UI, surface them in English (optionally `code-style` wrapped): + +- "你需要 owner 权限" +- "已切换到 in_progress" + +### Word combination rules + +Always put **a single space** between an English word (entity / brand / acronym) and surrounding Chinese: + +- "Create new issue" → "新建 issue" +- "Assign to agent" → "分配给智能体" +- "Configure runtime" → "配置运行时" +- "Stop daemon" → "停止守护进程" + +### Plurals and counts + +i18next uses `_one` / `_other`; Chinese has no grammatical number, only fill `_other`. + +```json +// en/issues.json +{ + "issue_count_one": "{{count}} issue", + "issue_count_other": "{{count}} issues" +} + +// zh-Hans/issues.json +{ + "issue_count_other": "{{count}} 个 issue" +} +``` + +Common count formats: + +- `{{count}} issues` → `{{count}} 个 issue` +- `{{count}} agents` → `{{count}} 个智能体` +- `{{count}} workspaces` → `{{count}} 个工作区` +- `{{count}} comments` → `{{count}} 条评论` +- `{{count}} members` → `{{count}} 位成员` +- `{{count}} skills` → `{{count}} 个 skill` + +### Interpolation + +Use `{{var}}`. Chinese translations may reorder for natural sentence flow. + +```json +// en +{ "welcome_message": "Welcome back, {{name}}!" } + +// zh-Hans +{ "welcome_message": "欢迎回来，{{name}}！" } +``` + +### Translation key naming + +Three-level nesting: `feature.component.action`. + +```json +{ + "feature_or_component": { + "subcomponent_or_section": { + "action_or_label": "..." + } + } +} +``` + +Examples: + +- `issues.toolbar.batch_update_success` +- `issues.detail.comment_form.placeholder` +- `inbox.empty.title` +- `settings.appearance.language.title` + +### Web-only / desktop-only copy + +- Shared copy: top level of the namespace JSON +- Web-only: `web` section +- Desktop-only: `desktop` section + +See `auth.json` for the canonical example (the `web` section contains `prefer_desktop` / `desktop_handoff.*`). + +--- + +## 3. Chinese voice and style + +### Punctuation + +- Full-width punctuation in Chinese: `，。：；！？` +- Quotes: straight double quotes `"..."` to match the English source. Do not use `「」` or curly quotes. +- Ellipsis: three dots `...` not the single character `…`. Match the English source. +- Mixed Chinese-English: a single space on each side of the English word (see Word combination rules). + +### Style principles + +- **Concise and direct.** Avoid translation-ese: "对于 X 来说"、"作为 X"、"我们的"。 +- **Error messages**: gentle but clear. "无法保存修改" beats "保存修改失败了！". +- **Buttons**: verb first, 2–4 characters. "取消"、"保存修改"、"立即同步". +- **Tooltips**: full short sentence. "复制链接到剪贴板". +- **Placeholders**: example-style. "输入 issue 标题...". + +### Where to look when in doubt + +When the glossary doesn't cover a term, look at: + +1. `apps/docs/content/docs/*.zh.mdx` — the de facto Chinese voice standard, 20+ pages of consistent translation +2. `packages/views/locales/zh-Hans/auth.json` and `editor.json` — JSON structure + selector API patterns +3. `packages/views/auth/login-page.tsx` — component-level selector API call site +4. `packages/views/settings/components/appearance-tab.tsx` — language switcher reference + +--- + +## Updating this page + +If you change a rule here, also: + +1. Apply it in the relevant locale JSONs / CLAUDE.md / docs page +2. Note the change in the PR description so reviewers know to look for downstream sweep + +This page is the contract; nothing else overrides it. diff --git a/apps/docs/content/docs/developers/conventions.zh.mdx b/apps/docs/content/docs/developers/conventions.zh.mdx new file mode 100644 index 0000000000..c940282cdd --- /dev/null +++ b/apps/docs/content/docs/developers/conventions.zh.mdx @@ -0,0 +1,285 @@ +--- +title: 规范 +description: 代码命名规范、i18n 翻译术语表、中文风格指南的唯一权威来源。 +--- + +本页是代码命名规范、i18n 翻译术语表、中文风格指南的唯一权威来源。原本散落在 `packages/views/locales/glossary.md` 和各处注释里的规则现在都收拢到这里。 + +写 Multica 代码、改翻译、写中文产品文案，都从这一页查。 + +--- + +## 1. 代码命名 + +### 路由 + +工作区前置路由（用户进入工作区之前能访问的路由）必须用单个单词，或者 `/{noun}/{verb}` 格式。 + +- ✅ `/login`、`/inbox`、`/workspaces/new` +- ❌ `/new-workspace`、`/create-team`、`/accept-invite` + +根目录的连字符词组会跟用户自选 workspace slug 冲突，逼着团队不停审保留字列表。把名词（`workspaces`）保留下来，整个 `/workspaces/*` 子树自动受保护。 + +### 工作区路由 + +永远用 `/{slug}/{section}` —— `/{slug}/issues`、`/{slug}/agents`、`/{slug}/settings`。共享代码不要复制路由逻辑，统一走 `useNavigation().push()`，不要直接用框架的 link API。 + +### 包与模块 + +monorepo 的包边界是硬约束： + +| 包 | 可依赖 | 不能依赖 | +| --- | --- | --- | +| `packages/core` | 仅平台无关基础库 | `react-dom`、`localStorage`、`process.env`、`next/*`、UI 库 | +| `packages/ui` | 无业务依赖 | `@multica/core`、业务逻辑 | +| `packages/views` | `core/`、`ui/` | `next/*`、`react-router-dom`、stores | +| `apps/web/platform/` | `next/*` | 其他 app | +| `apps/desktop/.../platform/` | `react-router-dom`、electron | 其他 app | + +两个 app 都有的逻辑，**必须**抽到共享包。"小段重复"也不算例外。 + +### 文件与组件 + +- 文件名：`kebab-case.tsx` / `kebab-case.ts`（如 `agent-row-actions.tsx`） +- 组件：`PascalCase`（如 `AgentRowActions`） +- Hook：`useCamelCase`（如 `useWorkspaceId`） +- 测试：与源文件同目录，命名 `.test.ts(x)` +- Zustand store：`-store.ts`，导出名 `useStore` + +### 数据库（Go + sqlc） + +- 表名：`snake_case` 单数（`user`、`workspace`、`agent_runtime`） +- 字段：`snake_case`（`workspace_id`、`created_at`、`last_seen_at`） +- 外键：`
_id` +- 布尔：`is_` 或者 `_at`（状态变化优先用时间戳形式） +- 迁移文件：`NNN_descriptive_name.up.sql` + `.down.sql`，**永远写双向** + +### Go + +- 标准 `gofmt` + `go vet`，无例外 +- Handler 文件按域命名：`agent.go`、`auth.go`、`runtime.go` +- 测试：`_test.go` 同目录 +- handler 里 UUID 解析遵守根 `CLAUDE.md` 的规则：边界输入用 `parseUUIDOrBadRequest`，可信回环用 `parseUUID`（panic 版），永远不要直接用 `util.ParseUUID` 不查 error + +### TypeScript + +- 网络上 API 响应是 `snake_case`，api client 在边界处转成 `camelCase`。**TS 代码内部一律 camelCase** +- 类型：`PascalCase`（`Issue`、`AgentRuntime`），不加 `IPrefix`，不加 `_t` 后缀 +- 枚举：优先用 string literal union，需要 runtime 迭代时才用 `enum` +- TanStack Query key：用 `/queries.ts` 里的工厂函数，例如 `issueKeys.detail(id)` + +### Issue 编号 + +每个 issue 有人类可读的编号，比如 `MUL-123`：工作区 `issue_prefix`（3 个大写字母）+ 流水号。前缀在工作区创建时定，之后不可改。 + +### 代码注释 + +**只允许英文**。Go 和 TypeScript 都强制。如果在代码里看到中文注释，那就是 bug，替换掉。 + +### Commit message + +Conventional 格式：`feat(scope)`、`fix(scope)`、`refactor(scope)`、`docs`、`test(scope)`、`chore(scope)`。按意图原子化分组。 + +--- + +## 2. i18n 翻译术语表 + +这是每个翻译 PR 都必须遵守的术语表。原本在 `packages/views/locales/glossary.md`，那个文件现在是个 stub，指向这一页。 + +### 核心区分：实体 vs 概念 + +Multica 的产品名词分两类： + +- **实体（typed entity）** —— 有 URL、有数据库 row、是 API 响应里某种 type 的东西。中文里**用小写英文**呈现，视觉上像类型名，告诉读者"这是 Multica 系统里的特定实体"。 +- **概念（concept）** —— 不是数据库实体的普通名词。**完整翻译成中文**，CN 用户看不到生硬的英文。 + +这套规则与 `apps/docs/content/docs/*.zh.mdx` 完全对齐 —— docs 是已经实战 20+ 篇的 CN voice 标准。 + +### 不翻 —— 实体（小写英文） + +| 词 | 中文中的写法 | 例 | +| --- | --- | --- | +| Issue | `issue`（小写） | "把 issue 分配给智能体"、"创建子 issue" | +| Project | `project`（小写） | "归入某个 project" | +| Skill | `skill`（小写） | "为智能体注入 skill" | +| Autopilot | `autopilot`（小写） | "新建 autopilot" | +| Task | `task`（小写） | "排队中的 task" | + +### 不翻 —— 品牌名 + 通用缩写 + +| 类别 | 词 | +| --- | --- | +| 品牌 | **Multica**、GitHub、Slack、Google、Anthropic、OpenAI、Claude、Codex、Cursor、Linear、Jira | +| 缩写 | API、CLI、URL、SDK、OAuth、JWT、SSO、WebSocket、HTTP、JSON、YAML、SQL | + +### 完整翻译 —— 概念词 + +| 英 | 中 | +| --- | --- | +| Workspace | **工作区** | +| Agent | **智能体** | +| Daemon | **守护进程** | +| Runtime | **运行时** | +| Inbox | **收件箱** | +| Comment | **评论** | +| Reply | **回复** | +| Notifications | **通知** | +| Member | **成员** | +| Label | **标签** | +| Settings | **设置** | +| Onboarding | **上手引导** | + +### 完整翻译 —— 通用 UI 词 + +| 英 | 中 | +| --- | --- | +| Invite / Invitation | 邀请 | +| Search | 搜索 | +| Email | 邮箱（label）/ 邮件（action） | +| Password | 密码 | +| Sign in / Log in | 登录 | +| Sign up | 注册 | +| Sign out / Log out | 退出登录 | +| Save / Cancel / Delete | 保存 / 取消 / 删除 | +| Confirm / Continue / Back | 确认 / 继续 / 返回 | +| Edit / New / Create / Add | 编辑 / 新建 / 创建 / 添加 | +| Remove / Send / Open / Close | 移除 / 发送 / 打开 / 关闭 | +| Done / Loading... | 完成 / 加载中... | +| Profile / Account / Appearance | 个人资料 / 账号 / 外观 | +| Theme / Language | 主题 / 语言 | +| Light / Dark / System | 浅色 / 深色 / 跟随系统 | +| Active / Archived | 活跃（或 启用）/ 已归档 | +| Status / Priority | 状态 / 优先级 | +| Assignee / Reporter | 负责人 / 报告人 | +| Description / Title | 描述 / 标题 | +| Date / Time | 日期 / 时间 | +| Today / Yesterday / Tomorrow | 今天 / 昨天 / 明天 | +| Empty / Failed / Success | 空 / 失败 / 成功 | +| Error / Warning | 错误 / 警告 | + +### 角色名 + 状态名（小写英文，不翻） + +这些是 schema-level 标识符，中文环境也保持小写英文： + +- 角色：`owner` / `admin` / `member` +- Issue 状态：`backlog` / `todo` / `in_progress` / `in_review` / `done` / `blocked` / `cancelled` + +UI 里展示这些值时保持英文（必要时用 code-style 包起来）： + +- "你需要 owner 权限" +- "已切换到 in_progress" + +### 词组组合规则 + +英文词（实体名 + 品牌名 + 缩写）与中文之间**加单空格**： + +- "Create new issue" → "新建 issue" +- "Assign to agent" → "分配给智能体" +- "Configure runtime" → "配置运行时" +- "Stop daemon" → "停止守护进程" + +### 复数与计数 + +i18next 用 `_one` / `_other`；中文不区分语法单复数，只填 `_other`。 + +```json +// en/issues.json +{ + "issue_count_one": "{{count}} issue", + "issue_count_other": "{{count}} issues" +} + +// zh-Hans/issues.json +{ + "issue_count_other": "{{count}} 个 issue" +} +``` + +常见计数格式： + +- `{{count}} issues` → `{{count}} 个 issue` +- `{{count}} agents` → `{{count}} 个智能体` +- `{{count}} workspaces` → `{{count}} 个工作区` +- `{{count}} comments` → `{{count}} 条评论` +- `{{count}} members` → `{{count}} 位成员` +- `{{count}} skills` → `{{count}} 个 skill` + +### 插值 + +用 `{{var}}` 形式。中文翻译可以调整位置以符合中文语序。 + +```json +// en +{ "welcome_message": "Welcome back, {{name}}!" } + +// zh-Hans +{ "welcome_message": "欢迎回来，{{name}}！" } +``` + +### Key 命名约定 + +3 层嵌套：`feature.component.action`。 + +```json +{ + "feature_or_component": { + "subcomponent_or_section": { + "action_or_label": "..." + } + } +} +``` + +实例： + +- `issues.toolbar.batch_update_success` +- `issues.detail.comment_form.placeholder` +- `inbox.empty.title` +- `settings.appearance.language.title` + +### Web-only / Desktop-only 文案位置 + +- 共享文案：放 namespace JSON 顶层 +- Web-only：放 `web` 段 +- Desktop-only：放 `desktop` 段 + +参考 `auth.json`（`web` 段含 `prefer_desktop` / `desktop_handoff.*`）。 + +--- + +## 3. 中文风格 + +### 标点 + +- 中文用全角标点：`，。：；！？` +- 引号：用 `"..."`（直引号），与英文 source 保持一致。**不要**用 `「」` 或弯引号 +- 省略号：用 `...`（三点）而非 `…`（单字符），与英文 source 保持一致 +- 中英混排：英文词左右各加 1 个空格（详见词组组合规则） + +### 风格原则 + +- **简洁直白**：避免翻译腔，"对于 X 来说"、"作为 X"、"我们的" +- **错误信息**：温和但明确，"无法保存修改" 优于 "保存修改失败了！" +- **按钮**：动词开头，2-4 字最佳。"取消"、"保存修改"、"立即同步" +- **Tooltip**：完整短句。"复制链接到剪贴板" +- **placeholder**：示例性提示。"输入 issue 标题..." + +### 拿不准的时候去哪查 + +术语表没覆盖的词，按这个顺序查： + +1. `apps/docs/content/docs/*.zh.mdx` —— CN voice 事实标准，20+ 篇高度一致 +2. `packages/views/locales/zh-Hans/auth.json` 和 `editor.json` —— JSON 结构 + selector API 用法参考 +3. `packages/views/auth/login-page.tsx` —— 组件层 selector API 调用参考 +4. `packages/views/settings/components/appearance-tab.tsx` —— 语言切换器参考 + +--- + +## 修改这一页时 + +改本页规则的同时还要： + +1. 把规则在相关 locale JSON / CLAUDE.md / docs 页面里同步落地 +2. PR 描述里写明改了什么，方便 reviewer 检查下游是否跟着改了 + +本页是契约，其他文档不能 override。 diff --git a/apps/docs/content/docs/developers/meta.json b/apps/docs/content/docs/developers/meta.json new file mode 100644 index 0000000000..8aa9ab8c10 --- /dev/null +++ b/apps/docs/content/docs/developers/meta.json @@ -0,0 +1,4 @@ +{ + "title": "Developers", + "pages": ["conventions"] +} diff --git a/apps/docs/content/docs/developers/meta.zh.json b/apps/docs/content/docs/developers/meta.zh.json index bb9377400b..a3ecbd2741 100644 --- a/apps/docs/content/docs/developers/meta.zh.json +++ b/apps/docs/content/docs/developers/meta.zh.json @@ -1,4 +1,4 @@ { "title": "Developers", - "pages": ["contributing", "architecture"] + "pages": ["contributing", "architecture", "conventions"] } diff --git a/apps/docs/content/docs/meta.json b/apps/docs/content/docs/meta.json index 2b8791b124..0df3cec31a 100644 --- a/apps/docs/content/docs/meta.json +++ b/apps/docs/content/docs/meta.json @@ -32,6 +32,8 @@ "---Reference---", "cli", "auth-tokens", - "desktop-app" + "desktop-app", + "---Developers---", + "developers" ] } diff --git a/apps/docs/content/docs/meta.zh.json b/apps/docs/content/docs/meta.zh.json index 691a196a75..32f5f9a8d9 100644 --- a/apps/docs/content/docs/meta.zh.json +++ b/apps/docs/content/docs/meta.zh.json @@ -32,6 +32,8 @@ "---参考---", "cli", "auth-tokens", - "desktop-app" + "desktop-app", + "---开发者---", + "developers" ] } diff --git a/packages/views/locales/glossary.md b/packages/views/locales/glossary.md index 01c1da4efd..70eb3f875a 100644 --- a/packages/views/locales/glossary.md +++ b/packages/views/locales/glossary.md @@ -1,209 +1,12 @@ # Multica i18n 术语表 (Glossary) -> **所有翻译 agent 必读**。任何 PR 翻译都必须遵守此表。 -> 不在表里的词，按"翻译风格"段处理。 +> **本文件已迁移**。所有翻译规范、命名规范、中文风格指南现在统一在 docs 站维护： +> +> - 中文：[`apps/docs/content/docs/developers/conventions.zh.mdx`](../../../apps/docs/content/docs/developers/conventions.zh.mdx) +> - English: [`apps/docs/content/docs/developers/conventions.mdx`](../../../apps/docs/content/docs/developers/conventions.mdx) +> +> 翻译 PR 必读那一份文档，不要参考此处。 -## 核心区分：实体 vs 概念 +如果你看到的是 git 历史里的旧版本，对应规则在 docs 站的「Conventions」页面里都能找到，按 `## 2. i18n 翻译术语表` / `## 3. 中文风格` 两段查询。 -Multica 的产品名词分两类，处理方式完全不同： - -- **实体（typed entity）** — 有 URL、有数据库 row、是 API 响应里某种 type 的东西。中文里**用小写英文**呈现，视觉上像类型名，告诉读者"这是 Multica 系统里的特定实体"。 -- **概念（concept）** — 不是数据库实体的普通名词。**完整翻译成中文**，CN 用户看不到生硬的英文。 - -这套规则与 `apps/docs/content/docs/*.zh.mdx` 完全对齐——docs 是已经实战 20+ 篇的 CN voice 标准。 - -## 不翻 — 实体（小写英文） - -| 词 | 中文中的写法 | 例 | -|---|---|---| -| Issue | `issue`（小写） | "把 issue 分配给智能体"、"创建子 issue" | -| Project | `project`（小写） | "归入某个 project" | -| Skill | `skill`（小写） | "为智能体注入 skill" | -| Autopilot | `autopilot`（小写） | "新建 autopilot" | -| Task | `task`（小写） | "排队中的 task" | - -## 不翻 — 品牌名 + 通用缩写 - -| 类别 | 词 | -|---|---| -| 品牌 | **Multica**、GitHub、Slack、Google、Anthropic、OpenAI、Claude、Codex、Cursor、Linear、Jira | -| 缩写 | API、CLI、URL、SDK、OAuth、JWT、SSO、WebSocket、HTTP、JSON、YAML、SQL | - -## 完整翻译 — 概念词（必须翻） - -| 英 | 中 | -|---|---| -| Workspace | **工作区** | -| Agent | **智能体** | -| Daemon | **守护进程** | -| Runtime | **运行时** | -| Inbox | **收件箱** | -| Comment | **评论** | -| Reply | **回复** | -| Notifications | **通知** | -| Member | **成员** | -| Label | **标签** | -| Settings | **设置** | -| Onboarding | **上手引导** | - -## 完整翻译 — 通用业务词 - -| 英 | 中 | -|---|---| -| Invite / Invitation | 邀请 | -| Search | 搜索 | -| Email | 邮箱（label）/ 邮件（action） | -| Password | 密码 | -| Sign in / Log in | 登录 | -| Sign up | 注册 | -| Sign out / Log out | 退出登录 | -| Save | 保存 | -| Cancel | 取消 | -| Delete | 删除 | -| Confirm | 确认 | -| Continue | 继续 | -| Back | 返回 | -| Edit | 编辑 | -| New | 新建 | -| Create | 创建 | -| Add | 添加 | -| Remove | 移除 | -| Send | 发送 | -| Open | 打开 | -| Close | 关闭 | -| Done | 完成 | -| Loading... | 加载中... | -| Profile | 个人资料 | -| Account | 账号 | -| Appearance | 外观 | -| Theme | 主题 | -| Language | 语言 | -| Light / Dark / System | 浅色 / 深色 / 跟随系统 | -| Active | 活跃 / 启用 | -| Archived | 已归档 | -| Status | 状态 | -| Priority | 优先级 | -| Assignee | 负责人 | -| Reporter | 报告人 | -| Description | 描述 | -| Title | 标题 | -| Date / Time | 日期 / 时间 | -| Today / Yesterday / Tomorrow | 今天 / 昨天 / 明天 | -| Empty | 空 | -| Failed | 失败 | -| Success | 成功 | -| Error | 错误 | -| Warning | 警告 | - -## 角色名 + 状态名（lowercase EN，不翻） - -角色名和状态枚举值是 schema-level 标识符，保持小写英文： - -- 角色：`owner` / `admin` / `member` -- Issue 状态：`backlog` / `todo` / `in_progress` / `in_review` / `done` / `blocked` / `cancelled` - -UI 里展示这些 schema 值时，保持英文（必要时用 code-style 包起来）： -- "你需要 owner 权限"、"已切换到 in_progress"。 - -## 词组组合规则 - -英文词（实体名 + 品牌名 + 缩写）与中文之间**加单空格**： - -- "Create new issue" → "新建 issue" -- "Assign to agent" → "分配给智能体" -- "Open workspace" → "打开工作区" -- "Configure runtime" → "配置运行时" -- "Edit comment" → "编辑评论" -- "Delete label" → "删除标签" -- "Stop daemon" → "停止守护进程" - -复数 / 量词： - -- `{{count}} issues` → `{{count}} 个 issue` -- `{{count}} agents` → `{{count}} 个智能体` -- `{{count}} workspaces` → `{{count}} 个工作区` -- `{{count}} comments` → `{{count}} 条评论` -- `{{count}} members` → `{{count}} 位成员` -- `{{count}} skills` → `{{count}} 个 skill` - -## Key 命名约定 - -3 层嵌套：`feature.component.action` - -```json -{ - "feature_or_component": { - "subcomponent_or_section": { - "action_or_label": "..." - } - } -} -``` - -实例： - -- `issues.toolbar.batch_update_success` -- `issues.detail.comment_form.placeholder` -- `inbox.empty.title` -- `settings.appearance.language.title` - -## 复数处理 - -- 英文：`key_one` / `key_other`（i18next 标准） -- 中文：**只**填 `_other`（中文不区分单复数） - -```json -// en/issues.json -{ - "issue_count_one": "{{count}} issue", - "issue_count_other": "{{count}} issues" -} - -// zh-Hans/issues.json -{ - "issue_count_other": "{{count}} 个 issue" -} -``` - -## 插值 - -- 用 `{{var}}` 形式 -- 中文翻译可调整位置以符合中文语序 - -```json -// en -"welcome_message": "Welcome back, {{name}}!" - -// zh-Hans -"welcome_message": "欢迎回来，{{name}}！" -``` - -## 标点 + 排版 - -- 中文：用全角标点（，。：；！？） -- 引号：用 `"` `"`（直引号），与英文 source 保持一致 -- 省略号：用 `...`（三点）而非 `…`（单字符），与英文 source 保持一致 -- 中英混排：英文词左右各**加 1 个空格** - -## 翻译风格 - -- **简洁直白**：避免"对于...来说"、"作为..."、"我们的"等翻译腔 -- **错误信息**：温和但明确（"无法保存修改" 而非 "保存修改失败了！"） -- **按钮**：动词开头，2-4 字最佳（"取消"、"保存修改"、"立即同步"） -- **Tooltip**：完整短句（"复制链接到剪贴板"） -- **placeholder**：示例性提示（"输入 issue 标题..."） - -## 参考实现 - -- `apps/docs/content/docs/*.zh.mdx` —— **CN voice 的事实标准**，20+ 篇高度一致的实战翻译 -- `packages/views/locales/zh-Hans/auth.json` + `editor.json` —— JSON 结构 + selector API 用法参考 -- `packages/views/auth/login-page.tsx` —— 组件层 selector API 调用参考 -- `packages/views/settings/components/appearance-tab.tsx` —— 含 Language 切换器的参考 - -## Web-only / Desktop-only 文案位置 - -- 共享文案放 `{ns}.json` 顶层 -- web-only 文案放 `{ns}.json` 的 `web` 段 -- desktop-only 文案放 `{ns}.json` 的 `desktop` 段 - -参考 `auth.json` 的 `web` 段（包含 `prefer_desktop` / `desktop_handoff.*`）。 +修改规则只能在 docs 站改，本文件不再维护。