規約 | Multica Docs

コードのネーミング、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	搜索
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	移除 / 发送 / 打开 / 关闭
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_success
issues.detail.comment_form.placeholder
inbox.empty.title
settings.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 の説明に変更点を記録し、レビュアーが下流の一括対応を確認できるようにする

このページが契約です。他の何ものもこれを上書きできません。

規約