규약

이 페이지는 코드 네이밍, 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()를 사용하세요.

패키지와 모듈

모노레포는 엄격한 패키지 경계를 강제합니다:

두 앱 모두에 동일한 로직이 나타난다면 반드시 공유 패키지로 추출해야 합니다. "사소한" 중복이라는 예외는 없습니다. Mobile은 독립된 UI, 데이터 계층, 출시 절차를 가지며 유형과 순수 함수만 공유합니다.

파일과 컴포넌트

• 파일: 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 — 항상 양방향을 모두 제공
• 데이터베이스 foreign key, cascade delete, cascade update를 만들지 않고 관계 검사와 정리는 애플리케이션 계층에서 수행
• 모든 index는 CREATE INDEX CONCURRENTLY 또는 CREATE UNIQUE INDEX CONCURRENTLY를 사용하고 각 concurrent index를 단일 문장 migration 파일에 분리

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).

API 경계

• 네트워크 응답은 packages/core/api/schema.ts의 parseWithFallback과 zod schema로 parsing하며 as T로 직접 강제 변환하지 않음
• endpoint를 추가하거나 변경할 때 schema도 업데이트하고 필드 누락 또는 잘못된 형식을 테스트로 포함
• 하위 UI는 선택 필드에 기본값을 제공하고 서버 enum의 switch에는 반드시 default 분기를 포함
• 설치된 Desktop이 더 새로운 backend에 연결될 수 있으므로 프런트엔드와 backend가 항상 같은 버전이라고 가정하지 않음

태스크 키

모든 태스크에는 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에 있었는데, 그 파일은 삭제되었고 이 페이지가 대체합니다.

핵심 구분: 일상어 vs Multica 고유어

Multica의 제품 명사는 두 가지 범주로 나뉩니다:

• 일상어 — 사용자가 소리 내어 말하는 단어입니다. 데이터베이스 엔티티인지와 무관하게 완전히 번역합니다: issue → 태스크, workspace → 워크스페이스, project → 프로젝트.
• Multica 고유어 — 해당 언어에 대응하는 단어가 없는 개념(skill), 또는 사용자가 직접 입력하거나 대조해야 하는 스키마 수준 식별자(todo, in_progress, task_id). 소문자 영문으로 표기해 타입 이름처럼 읽히게 합니다.

apps/docs/content/docs/*.zh.mdx는 이 페이지의 나머지 모든 것에 대한 사실상의 보이스 표준입니다. *.zh.mdx / *.ja.mdx / *.ko.mdx의 본문도 이제 아래 표를 따릅니다.

issue는 제품의 "태스크" — 번역합니다

issue는 사용자가 등록하고 에이전트가 처리하는 대상의 영어 제품 이름입니다. 영어가 아닌 모든 로케일에서는 그 언어에서 일상적으로 "태스크"를 뜻하는 단어가 됩니다:

두 명사 모두 사용자에게 보이며, 같은 것이 아닙니다 — 하나의 issue가 여러 번의 실행을 가질 수 있습니다. 어떤 로케일에서도 둘을 같은 단어로 적어서는 안 되며, 그래서 실행은 각 로케일에서 시각적으로 구별되는 형태를 유지합니다.

바뀌지 않는 것:

• API / DB 필드는 어디서나 issue / task / skill: issue_status, task_id, skill_uuid.
• 코드 참조와 명령어 리터럴은 영문 유지: multica issue ..., Slack과 Lark의 /issue slash 명령.
• **skill**은 중국어 텍스트에서도 소문자 영문 유지 — 정착된 번역어가 없는 Multica 고유 개념이며, 제목에서는 Skills처럼 대문자로 쓸 수 있습니다.
• "문제" 의미의 issue(런타임 헬스)는 엔티티가 아니라 일반 명사입니다. 머신 카드의 {{count}} issues는 {{count}} 个异常 / 問題 {{count}} 件 / 문제 {{count}}개이며, 엔티티 단어를 쓰지 않습니다.

왜 issue는 번역하고 skill은 번역하지 않는가: 사용자는 매일 issue를 등록하고 읽습니다. 그리고 "issue"라는 단어는 중국어·일본어·한국어에서 개발자 은어를 빼면 아무 의미가 없습니다. 현지 사용자가 원래 이 대상을 가리켜 쓰는 말은 "태스크"에 해당하는 일상어입니다. skill은 그 의미를 담을 현지어가 없는 Multica 고유 개념입니다.

다른 제품 명사도 "정착된 현지어가 있는가"라는 같은 기준으로 판단합니다:

• project → "项目": 정착된 주류 중국어 단어. Feishu / Tower / Teambition / PingCode / GitHub Projects — 모든 중국어 제품이 이를 번역합니다. 중국어 맥락에서 project를 그대로 두는 제품은 없습니다.
• autopilot → "自动化": 중국어에서 "autopilot"은 Tesla의 "自动驾驶"를 연상시키며, 이 기능이 하는 일(일정에 따라 task 실행)과 맞지 않습니다. Notion과 Feishu 모두 "自动化"를 사용하며, 그것이 업계 합의입니다.

번역하지 않음 — 브랜드와 약어

완전히 번역 — 개념

완전히 번역 — 일반 UI 단어

역할과 상태 열거형 (소문자 영문, 번역하지 않음)

이것들은 스키마 수준의 식별자입니다; 중국어 맥락에서도 소문자 영문으로 표기합니다.

• 역할: owner / admin / member
• 태스크 상태: backlog / todo / in_progress / in_review / done / blocked / cancelled

UI에서는 이 값들을 영어로 표시합니다(필요 시 code-style로 감쌈):

• "你需要 owner 权限"
• "已切换到 in_progress"

단어 조합 규칙

영문 단어(엔티티 / 브랜드 / 약어)와 주변 중국어 사이에는 항상 단일 공백을 둡니다:

• "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. 중국어 보이스와 스타일

구두점

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

스타일 원칙

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

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