規約

このページは、コードのネーミング、i18n 翻訳用語集、中国語ボイスガイドの単一の信頼できる情報源です。かつて packages/views/locales/glossary.md やあちこちに散らばったコメントにあった内容は、現在すべてここに集約されています。

Clowld Space のコードを書く、翻訳を変更する、あるいは中国語の製品コピーを書く場合は、このページを参照してください。

用語と概念の信頼できる情報源

• 製品オブジェクトの固定名称、意味、関係は docs/知识库/开始使用/核心概念.md で定義し、公開ページ apps/docs/content/docs/concepts.zh.mdx も同じ意味を保ちます。
• コードのネーミング、i18n 用語集、中国語の製品文体はこのページで定義します。リポジトリ内の docs/知识库/开发者/开发规范.md は、Markdown のタイトルラッパーを除いて中国語ページと逐語的に同期しなければなりません。
• CONTEXT.md、別の glossary、並行するドメイン用語文書は作成しません。用語や概念を変更する場合は、影響するすべての情報源を同じ変更で更新し、矛盾を解消してからマージします。

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() を使用してください。

パッケージとモジュール

モノレポは厳格なパッケージ境界を強制します。

両方のアプリに同じロジックが現れる場合は、必ず共有パッケージに抽出しなければなりません。「ささいな」重複という例外はありません。Mobile は独自の UI、データ層、リリースフローを持ち、型と純粋関数だけを共有します。

ファイルとコンポーネント

• ファイル: 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 — 常に双方向を提供する
• データベースの foreign key、cascade delete、cascade update は作成せず、関係の検証とクリーンアップをアプリケーション層で行う
• すべてのインデックスで CREATE INDEX CONCURRENTLY または CREATE UNIQUE INDEX CONCURRENTLY を使用し、各 concurrent index を 1 文だけの migration ファイルに分ける

Go

• 標準の gofmt + go vet。例外なし。
• Handler ファイルはドメインを反映する: agent.go, auth.go, runtime.go
• テスト: <file>_test.go を同じ場所に配置
• handler での UUID パースは、ルートの AGENTS.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)。

API 境界

• ネットワークレスポンスは packages/core/api/schema.ts の parseWithFallback と zod schema で解析し、as T で直接キャストしない
• endpoint を追加または変更するときは schema も更新し、フィールド欠落や形式不正をテストで網羅する
• 下流 UI は任意フィールドにデフォルト値を用意し、サーバー enum の switch には必ず default 分岐を設ける
• インストール済みの Desktop がより新しい backend に接続する場合があるため、フロントエンドとバックエンドが常に同じバージョンだと仮定しない

タスクキー

すべてのタスクには CS-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 にありましたが、そのファイルは削除され、このページが置き換えています。

中核となる区別: 日常語 vs Clowld Space 固有の用語

Clowld Space の製品名詞は 2 つのカテゴリに分かれます。

• 日常語 — ユーザーが普段そのまま口にする語です。データベースエンティティかどうかに関係なく完全に中国語へ翻訳します。例: issue → 任务、workspace → 工作区、topic → 主题。
• Clowld Space 固有の用語 — 中国語に対応語がない概念（skill）、またはユーザーが入力・照合する schema 識別子（todo、in_progress、task_id）です。識別子自体を表示するときだけ小文字の英語を保ち、UI の表示名はローカライズします。

中国語ページ apps/docs/content/docs/*.zh.mdx は、それ以外の中国語文体の標準です。本文では製品エンティティを「任务」と呼び、生の issue はコマンド、フィールド、URL、コード、明示的な用語説明にだけ残します。また、*.ja.mdx と *.ko.mdx の本文も下の表に従います。

issue は製品上の「タスク」— 必ず翻訳する

issue は、ユーザーが登録し、智能体が取り組む対象の英語製品名です。英語以外の各言語では、日常的な「タスク」に相当する語を使用します。

この 2 語はどちらもユーザーに見えますが、同じものではありません。1 つの任务から複数回の执行が生まれます。

変更しないもの:

• API / DB フィールドは常に issue / task / skill のままです。
• コード参照とリテラルコマンドは英語のままです。
• 実行の生識別子は、API、CLI 引数、ログ、コード例では task / task_id のままです。中国語のユーザー向け表示名だけを「执行」にします。
• skill は中国語本文でも小文字の英語を保ちます。見出しでは Skills を使用できます。
• plugin は中国語 UI と本文で「插件」と訳し、技術識別子だけ plugin を保ちます。
• 問題・異常を意味する一般名詞の issue は製品エンティティではありません。マシンカードの {{count}} issues は {{count}} 个异常 / 問題 {{count}} 件 / 문제 {{count}}개 であり、エンティティの語は使いません。

その他の製品名詞も、定着した日常語があるかどうかで判断します。

• topic → "主题": 関連する作業とコンテキストをまとめる共通方向です。
• autopilot → "自动化": スケジュールまたは外部イベントで実行を開始する機能です。
• Promotion → "晋级": 検証済みの dev スナップショットを凍結して main へ統合する Clowld のデリバリー操作です。Release（版本发布/发行）や Deployment（部署）とは区別します。技術識別子は英語のままです。

翻訳しない — ブランドと頭字語

完全に翻訳する — 概念

完全に翻訳する — 一般的な UI 用語

ロールと状態: 表示名は翻訳し、識別子は保持する

以下の schema 識別子は、API、DB、CLI、ログ、コード例では小文字の英語を保ちます。

• ロール: owner / admin / member
• タスクの状態: backlog / todo / in_progress / in_review / done / blocked / cancelled
• タスクの状態カテゴリ: unstarted / started / done / closed

中国語 UI と自然言語では組み込み表示名をローカライズします。ユーザーが識別子を入力・コピー・照合するときだけ生の英語を表示します。

• "你需要所有者权限"
• "已切换到进行中"

単語の組み合わせルール

英語の単語（エンティティ / ブランド / 頭字語）と周囲の中国語の間には、常に単一の空白を入れます。

• "Create new 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}} 个任务"
}

一般的な数の形式:

• {{count}} issues → {{count}} 个任务
• {{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 文字。"取消"、"保存修改"、"立即同步"。
• ツールチップ: 完結した短い文。"复制链接到剪贴板"。
• プレースホルダー: 例の形式。"输入任务标题..."。

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

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

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 / AGENTS.md / ドキュメントページに適用する
2. PR の説明に変更点を記録し、レビュアーが下流の一括対応を確認できるようにする

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