規約
コードのネーミング、i18n 翻訳用語集、中国語ボイスガイドの単一の信頼できる情報源。
このページは、コードのネーミング、i18n 翻訳用語集、中国語ボイスガイドの単一の信頼できる情報源です。かつて packages/views/locales/glossary.md やあちこちに散らばったコメントにあった内容は、現在すべてここに集約されています。
Multica のコードを書く、翻訳を変更する、あるいは中国語の製品コピーを書く場合は、このページを参照してください。
1. コードのネーミング
ルート
ワークスペース進入前のルート（ユーザーがワークスペースに入る前から存在するルート）は、必ず単一の単語または /{noun}/{verb} パターンを使用しなければなりません。
- ✅
/login,/inbox,/workspaces/new - ❌
/new-workspace,/create-team,/accept-invite
ルート直下のハイフンで連結した単語のまとまりは、ユーザーが自分で選んだワークスペースの slug と衝突し、際限のない予約 slug の監査を強いることになります。名詞（workspaces）を予約しておけば、/workspaces/* のサブツリー全体が自動的に保護されます。
ワークスペーススコープのルート
常に /{slug}/{section} の下に置きます — /{slug}/issues、/{slug}/agents、/{slug}/settings。ワークスペースのルーティングロジックを絶対に重複させず、共有コードではフレームワーク固有の link API ではなく useNavigation().push() を使用してください。
パッケージとモジュール
モノレポは厳格なパッケージ境界を強制します。
| パッケージ | 依存可能 | 依存禁止 |
|---|---|---|
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/* | 他のアプリ |
apps/desktop/.../platform/ | react-router-dom, electron | 他のアプリ |
両方のアプリに同じロジックが現れる場合は、必ず共有パッケージに抽出しなければなりません。「ささいな」重複という例外はありません。
ファイルとコンポーネント
- ファイル:
kebab-case.tsx/kebab-case.ts（例:agent-row-actions.tsx） - コンポーネント:
PascalCase（例:AgentRowActions） - フック:
useCamelCase（例:useWorkspaceId） - テスト:
<file>.test.ts(x)として同じ場所に配置 - ストア（Zustand）:
<feature>-store.ts、use<Feature>Storeとして export
データベース（Go + sqlc）
- テーブル:
snake_caseの単数形（user,workspace,agent_runtime） - カラム:
snake_case（workspace_id,created_at,last_seen_at） - 外部キー:
<table>_id - ブール値:
is_<state>または<state>_at（状態変更にはタイムスタンプ形式を推奨） - マイグレーションファイル:
NNN_descriptive_name.up.sql+.down.sql— 常に双方向を提供する
Go
- 標準の
gofmt+go vet。例外なし。 - Handler ファイルはドメインを反映する:
agent.go,auth.go,runtime.go - テスト:
<file>_test.goを同じ場所に配置 - handler での UUID パースは、ルートの
CLAUDE.mdのルールに従ってください — 境界の入力にはparseUUIDOrBadRequest、信頼できる往復にはparseUUID（panic 版）を使い、error を確認せずにutil.ParseUUIDを直接使用しないでください。
TypeScript
- ネットワーク上の API レスポンスは
snake_caseで、api client が境界でcamelCaseに変換します。TS コード内部では常に camelCase。 - 型:
PascalCase（Issue,AgentRuntime）；IPrefixは禁止、_tサフィックスも禁止。 - 列挙: string literal union を推奨し、ランタイムで反復処理が必要な場合にのみ
enumを使用。 - TanStack Query のキー:
<feature>/queries.ts内のファクトリ関数、例:issueKeys.detail(id)。
イシューキー
すべてのイシューには MUL-123 のような人が読めるキーがあります。ワークスペースの issue_prefix（大文字と数字、通常 3 文字、最大 10 文字）+ 連番です。ワークスペースの admin は Settings → General で接頭辞を変更できますが、変更すると既存のすべてのイシューが番号を振り直されるため、古い接頭辞が埋め込まれた外部参照（PR タイトル、ブランチ名、ドキュメントやチャット内のリンク）は解決されなくなります。
コード内のコメント
英語のみです。リポジトリは Go と TypeScript の両方でこれを強制します。コード内に中国語のコメントを見つけたら、それはバグなので置き換えてください。
コミットメッセージ
Conventional 形式: feat(scope), fix(scope), refactor(scope), docs, test(scope), chore(scope)。意図ごとにまとめられたアトミックなコミット。
2. i18n 翻訳用語集
これは、すべての翻訳 PR が必ず守らなければならない用語集です。かつては packages/views/locales/glossary.md にありましたが、そのファイルは現在ここを指す stub です。
中核となる区別: エンティティ vs 概念
Multica の製品名詞は 2 つのカテゴリに分かれます。
- エンティティ（Entity） — URL、データベースの row、API の型を持ちます。中国語のテキストでは小文字の英語で表記し、視覚的に型名のように読めて「これは Multica のシステムエンティティだ」というシグナルを与えます。
- 概念（Concept） — 一般名詞であり、データベースのエンティティではありません。完全に翻訳し、中国語ユーザーが流れるテキストの中にギザギザの英語を見ないようにします。
このルールは apps/docs/content/docs/*.zh.mdx と整合しています — これらのドキュメントは事実上の中国語ボイス標準であり、20 ページ以上で実戦検証されています。
エンティティ — 混合ルール（issue / skill / task）
issue / skill / task は Multica の中核エンティティです。スキーマのカラム、API のフィールド、製品 UI のラベルがすべて英語です。中国語のテキストでは混合ルールに従い、何を使うかは単語がどこに現れるかによって変わります。
| 文脈 | 表記 | 例 |
|---|---|---|
| UI 文字列、状態名、コード参照 | 小文字の英語 | "排队中的 task"、"创建子 issue"、"为智能体注入 skill" |
| ドキュメントのタイトル / セクション見出し | Title-case の英語 または 中国語の用語 | "Issue 与 project"、"Skills"、"执行任务" |
| 長文ドキュメントの本文で、エンティティが文の主語になっている場合 | 中国語の用語、初出時に括弧内に英語 | "执行任务（task）是智能体每一次工作的单位" |
| API / DB フィールド | 常に task / issue / skill | task_id, issue_status, skill_uuid |
中国語の用語の参考:
task↔执行任务（文脈が明確になれば任务に短縮）issueには定着した中国語訳がありません — 英語のまま；タイトルではIssueのように大文字にできますskillには定着した中国語訳がありません — 英語のまま；タイトルではSkillsのように大文字にできます
issue / skill / task が project / autopilot のように中国語へ強制的に翻訳されない理由:
issue/task: 開発チームは英語で会話します。中国語の候補（"任务" — あいまいすぎて "工作" とほぼ同義；"工单" — IT チケットのニュアンス；"议题" — GitHub 風だが製品の感覚に合わない）はいずれもissueよりも読みづらくなります。ただし、長文ドキュメントの本文で小文字のtaskを 50 回繰り返すとリズムが崩れるため、本文では执行任务を許容しつつ、UI 文字列と状態名は小文字の英語のままにします。skill: 定着した中国語の用語がない Multica 固有の概念です。project→ "项目": 定着した主流の中国語の単語です。Feishu / Tower / Teambition / PingCode / GitHub Projects — すべての中国語製品がこれを翻訳します。中国語の文脈でprojectをそのまま残す製品はありません。autopilot→ "自动化": 中国語で "autopilot" は Tesla の "自动驾驶" を連想させ、この機能が行うこと（スケジュールに従ってタスクを実行する）と合いません。Notion も Feishu も "自动化" を使っており、それが業界の合意です。
翻訳しない — ブランドと頭字語
| カテゴリ | 用語 |
|---|---|
| ブランド | Multica, GitHub, Slack, Google, Anthropic, OpenAI, Claude, Codex, Cursor, Linear, Jira |
| 頭字語 | API, CLI, URL, SDK, OAuth, JWT, SSO, WebSocket, HTTP, JSON, YAML, SQL |
完全に翻訳する — 概念
| English | Chinese |
|---|---|
| Workspace | 工作区 |
| Agent | 智能体 |
| Project | 项目 |
| Autopilot | 自动化 |
| Daemon | 守护进程 |
| Runtime | 运行时 |
| Inbox | 收件箱 |
| Comment | 评论 |
| Reply | 回复 |
| Notifications | 通知 |
| Member | 成员 |
| Label | 标签 |
| Settings | 设置 |
| Onboarding | 上手引导 |
完全に翻訳する — 一般的な UI 用語
| English | Chinese |
|---|---|
| Invite / Invitation | 邀请 |
| Search | 搜索 |
| 邮箱 (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 | 移除 / 发送 / 打开 / 关闭 |
| Preview / Download / Upload | 预览 / 下载 / 上传 |
| 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 | 错误 / 警告 |
ロールと状態の列挙型（小文字の英語、翻訳しない）
これらはスキーマレベルの識別子です。中国語の文脈でも小文字の英語で表記します。
- ロール:
owner/admin/member - イシューの状態:
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 のみを埋めます。
// 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}} を使います。中国語の翻訳では、自然な文章の流れのために順序を並べ替えてもかまいません。
// en
{ "welcome_message": "Welcome back, {{name}}!" }
// zh-Hans
{ "welcome_message": "欢迎回来，{{name}}！" }翻訳キーのネーミング
3 階層のネスト: feature.component.action。
{
"feature_or_component": {
"subcomponent_or_section": {
"action_or_label": "..."
}
}
}例:
issues.toolbar.batch_update_successissues.detail.comment_form.placeholderinbox.empty.titlesettings.preferences.language.title
Web 専用 / Desktop 専用のコピー
- 共有コピー: namespace JSON の最上位
- Web 専用:
webセクション - Desktop 専用:
desktopセクション
正式な例は auth.json を参照してください（web セクションに prefer_desktop / desktop_handoff.* が含まれます）。
3. 中国語のボイスとスタイル
句読点
- 中国語では全角の句読点を使用:
，。：；！？ - 引用符: 英語の原文に合わせて、まっすぐな二重引用符
"..."を使用。「」や丸い引用符は使わないでください。 - 省略記号: 単一文字の
…ではなく、3 つの点...。英語の原文に合わせてください。 - 中国語と英語の混在: 英語の単語の両側にそれぞれ単一の空白（単語の組み合わせルールを参照）。
スタイルの原則
- 簡潔かつ直接的に。 翻訳調を避ける: "对于 X 来说"、"作为 X"、"我们的"。
- エラーメッセージ: 穏やかだが明確に。"无法保存修改" は "保存修改失败了！" よりも優れています。
- ボタン: 動詞を先頭に、2〜4 文字。"取消"、"保存修改"、"立即同步"。
- ツールチップ: 完結した短い文。"复制链接到剪贴板"。
- プレースホルダー: 例の形式。"输入 issue 标题..."。
迷ったときに参照する場所
用語集が特定の用語を扱っていない場合は、次を参照してください。
apps/docs/content/docs/*.zh.mdx— 事実上の中国語ボイス標準、一貫した翻訳が 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/preferences-tab.tsx— 言語切り替えの参考
このページを更新するとき
ここのルールを変更した場合は、次も併せて行ってください。
- 関連する locale JSON / CLAUDE.md / ドキュメントページに適用する
- PR の説明に変更点を記録し、レビュアーが下流の一括対応を確認できるようにする
このページが契約です。他の何ものもこれを上書きできません。