---
title: 規約
description: コードのネーミング、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` のみを埋めます。

```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}}！" }
```

### 翻訳キーのネーミング

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.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 标题..."。

### 迷ったときに参照する場所

用語集が特定の用語を扱っていない場合は、次を参照してください。

1. `apps/docs/content/docs/*.zh.mdx` — 事実上の中国語ボイス標準、一貫した翻訳が 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/preferences-tab.tsx` — 言語切り替えの参考

---

## このページを更新するとき

ここのルールを変更した場合は、次も併せて行ってください。

1. 関連する locale JSON / CLAUDE.md / ドキュメントページに適用する
2. PR の説明に変更点を記録し、レビュアーが下流の一括対応を確認できるようにする

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