규약 | 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)
Hook: useCamelCase (예: useWorkspaceId)
테스트: <file>.test.ts(x)로 같은 위치에 배치
Store (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의 제품 명사는 두 가지 범주로 나뉩니다:

엔티티(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의 "自动驾驶"를 연상시키며, 이 기능이 하는 일(일정에 따라 task 실행)과 맞지 않습니다. 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. 중국어 보이스와 스타일

구두점

중국어에서는 전각 구두점 사용: ，。：；！？
따옴표: 영어 원문과 맞추기 위해 곧은 큰따옴표 "..."를 사용. 「」나 둥근 따옴표는 사용하지 마세요.
줄임표: 단일 문자 …가 아닌 세 개의 점 .... 영어 원문과 일치시키세요.
중국어-영어 혼용: 영문 단어 양옆에 각각 단일 공백(단어 조합 규칙 참고).

스타일 원칙

간결하고 직접적으로. 번역투 회피: "对于 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 설명에 변경 사항을 기록하여 리뷰어가 다운스트림 정리를 살펴보도록 알리기

이 페이지가 계약입니다; 다른 어떤 것도 이를 무시할 수 없습니다.

규약