Соглашения (Conventions)

Единый источник правды для именования кода, глоссария локализации i18n и руководства по стилю на русском языке.

Эта страница является единым источником правды для именования кода, глоссария локализации i18n и руководства по стилю для русского языка. Все, что ранее находилось в файле packages/views/locales/glossary.md или в разрозненных комментариях, теперь собрано здесь.

Если вы пишете код для PREDICTORX, меняете переводы или создаете тексты продукта на китайском языке, руководствуйтесь этой страницей.

1. Именование кода (Code naming)

Маршруты (Routes)

Маршруты до рабочего пространства (маршруты, которые существуют до того, как пользователь входит в рабочую область) ДОЛЖНЫ использовать либо одно слово, либо паттерн /{существительное}/{глагол}.

✅ /login, /inbox, /workspaces/new
❌ /new-workspace, /create-team, /accept-invite

Группы слов через дефис в корневом каталоге конфликтуют с выбранными пользователями слагами рабочих областей (workspace slugs) и вынуждают проводить бесконечные проверки зарезервированных слагов. Резервирование существительного (workspaces) автоматически защищает все поддерево /workspaces/*.

Маршруты внутри рабочей области (Workspace-scoped routes)

Всегда находятся по пути /{slug}/{section} — /{slug}/issues, /{slug}/agents, /{slug}/settings. Никогда не дублируйте логику маршрутизации рабочих областей; используйте useNavigation().push() из общего кода, а не специфичные для фреймворка API ссылок.

Пакеты и модули (Packages and modules)

Монорепозиторий строго контролирует границы пакетов:

Пакет	Может зависеть от	НЕ должен зависеть от
`packages/core`	ничего специфичного для приложения	`react-dom`, `localStorage`, `process.env`, `next/*`, UI-библиотек
`packages/ui`	ничего	`@predictorx/core`, бизнес-логики
`packages/views`	`core/`, `ui/`	`next/*`, `react-router-dom`, сторов
`apps/web/platform/`	`next/*`	других приложений
`apps/desktop/.../platform/`	`react-router-dom`, electron	других приложений

Если логика используется в обоих приложениях, она ДОЛЖНА быть вынесена в общий пакет. Исключений для «незначительного» дублирования не существует.

Файлы и компоненты (Files and components)

Файлы: 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

База данных (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. Без исключений.
Файлы обработчиков (handlers) соответствуют домену: agent.go, auth.go, runtime.go
Тесты: сопутствующие <file>_test.go
Для парсинга UUID в обработчиках следуйте правилу в корневом CLAUDE.md — parseUUIDOrBadRequest для входных данных на границе приложения, parseUUID (вызывающий panic) для доверенных внутренних цепочек вызовов, и никогда не используйте util.ParseUUID напрямую без проверки ошибки.

TypeScript

Ответы API по сети передаются в snake_case; клиент API конвертирует их в camelCase на границе приложения. Внутри кода на TS всегда используйте camelCase.
Типы: PascalCase (Issue, AgentRuntime); никогда не используйте префикс I и суффикс _t.
Перечисления (Enums): отдавайте предпочтение строковым литеральным объединениям (string literal unions); резервируйте enum только для случаев, требующих итерации во время выполнения (runtime-iterable).
Ключи TanStack Query: фабричные функции в <feature>/queries.ts, например issueKeys.detail(id).

Ключи задач (Issue keys)

Каждая задача имеет понятный человеку ключ вида MUL-123: префикс рабочей области issue_prefix (буквы в верхнем регистре и цифры, обычно 3 символа, максимум 10) + порядковый номер. Администраторы рабочей области могут изменить префикс в Настройки → Общие; изменение префикса приведет к перенумерации всех существующих задач, поэтому внешние ссылки, содержащие старый префикс (названия PR, имена веток, ссылки в документации и чате), перестанут работать.

Комментарии в коде

Только на английском языке. Репозиторий строго контролирует это как для Go, так и для TypeScript. Если вы нашли комментарий на китайском языке в коде — это баг, замените его.

Коммит-сообщения (Commit messages)

Конвенциональный формат: feat(scope), fix(scope), refactor(scope), docs, test(scope), chore(scope). Атомарные коммиты, сгруппированные по намерениям.

2. Глоссарий локализации i18n (i18n translation glossary)

Это обязательный глоссарий для каждого PR с переводом. Ранее он находился в packages/views/locales/glossary.md; теперь этот файл является заглушкой, ссылающейся сюда.

Основное различие: сущность против концепта

Существительные продукта PREDICTORX делятся на две категории:

Сущность (Entity) — имеет URL, строку в базе данных, тип API. В китайском тексте отображается английскими строчными буквами, чтобы визуально выглядеть как имя типа и сигнализировать: «это системная сущность PREDICTORX».
Концепт (Concept) — общее существительное, не являющееся сущностью БД. Переводится полностью, чтобы китайские пользователи не видели обрывочных английских слов в плавном тексте.

Это правило согласовано с apps/docs/content/docs/*.zh.mdx — эти документы являются фактическим стандартом китайского стиля и прошли проверку на более чем 20 страницах.

Сущности — смешанное правило (`issue` / `skill` / `task`)

issue / skill / task — это ключевые сущности PREDICTORX. У них есть колонки в схеме, поля API и лейблы в интерфейсе продукта, которые пишутся на английском языке. В китайском тексте они следуют смешанному правилу — формат использования зависит от контекста:

Контекст	Отображение	Пример
Строки интерфейса, названия состояний, ссылки в коде	английские строчные буквы	"排队中的 task", "创建子 issue", "为智能体注入 skill"
Заголовки документов / разделов	Английский в Title-case или китайский термин	"Issue 与 project", "Skills", "执行任务"
Длинная проза в документации, где сущность является подлежащим	Китайский термин с английским в скобках при первом упоминании	"执行任务（task）是智能体每一次工作的单位"
Поля API / БД	всегда `task` / `issue` / `skill`	`task_id`, `issue_status`, `skill_uuid`

Справочник китайских терминов:

task ↔ 执行任务 (или сокращенно 任务, когда контекст понятен)
issue не имеет устоявшегося перевода на китайский — оставляйте на английском; в заголовках можно писать с заглавной буквы Issue
skill не имеет устоявшегося перевода на китайский — оставляйте на английском; в заголовках можно писать с заглавной буквы Skills

Почему issue / skill / task не переводятся на китайский принудительно, в отличие от project / autopilot:

issue / task: команды разработчиков общаются на английском. Варианты на китайском ("任务" — слишком неопределенно, почти синоним "工作"; "工单" — ассоциация с ИТ-тикетами; "议题" — в стиле GitHub, но не соответствует духу продукта) звучат хуже, чем issue. Однако в длинной прозе документации повторение строчного task 50 раз нарушает ритм речи — поэтому в прозе разрешено использовать 执行任务, в то время как строки интерфейса и названия состояний остаются на английском языке в нижнем регистре.
skill: специфичный для PREDICTORX концепт, не имеющий устоявшегося китайского аналога.
project → "项目": устоявшееся общепринятое китайское слово. Feishu / Tower / Teambition / PingCode / GitHub Projects — каждый китайский продукт переводит его именно так. Ни один продукт не сохраняет project на английском в китайском контексте.
autopilot → "自动化": в китайском языке "autopilot" ассоциируется с автопилотом Tesla ("自动驾驶") и не отражает суть функции (выполнение задач по расписанию). И Notion, и Feishu используют "自动化"; это общеиндустриальный консенсус.

Не переводить — бренды и аббревиатуры

Категория	Термины
Бренды	PREDICTORX, GitHub, Slack, Google, Anthropic, OpenAI, Claude, Codex, Cursor, Linear, Jira
Аббревиатуры	API, CLI, URL, SDK, OAuth, JWT, SSO, WebSocket, HTTP, JSON, YAML, SQL

Переводить полностью — концепты

Английский	Китайский
Workspace	工作区
Agent	智能体
Project	项目
Autopilot	自动化
Daemon	守护进程
Runtime	运行时
Inbox	收件箱
Comment	评论
Reply	回复
Notifications	通知
Member	成员
Label	标签
Settings	设置
Onboarding	上手引导

Переводить полностью — общие элементы интерфейса

Английский	Китайский
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

В интерфейсе выводите их на английском языке (желательно оформляя как код):

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

Правила сочетания слов

Всегда ставьте один пробел между английским словом (сущностью / брендом / аббревиатурой) и окружающим китайским текстом:

"Create new issue" → "新建 issue"
"Assign to agent" → "分配给智能体"
"Configure runtime" → "配置运行时"
"Stop daemon" → "停止守护进程"

Множественные числа и подсчет (Plurals and counts)

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

Интерполяция (Interpolation)

Используйте {{var}}. Переводы на китайский язык могут менять порядок слов для обеспечения естественного звучания предложений.

// en
{ "welcome_message": "Welcome back, {{name}}!" }

// zh-Hans
{ "welcome_message": "欢迎回来，{{name}}！" }

Именование ключей перевода (Translation key naming)

Трехуровневая вложенность: 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

Общие тексты: верхний уровень JSON пространства имен
Только для Web: секция web
Только для Desktop: секция desktop

См. канонический пример в файле auth.json (секция web содержит ключи prefer_desktop / desktop_handoff.*).

3. Китайский голос и стиль (Chinese voice and style)

Пунктуация

Полноширинная пунктуация в китайском языке: ，。：；！？
Кавычки: прямые двойные кавычки "..." в соответствии с английским источником. Не используйте 「」 или фигурные кавычки.
Многоточие: три точки ... вместо единого символа …. Соответствует английскому источнику.
Смешанный китайско-английский текст: по одному пробелу с каждой стороны английского слова (см. Правила сочетания слов).

Принципы стиля

Лаконично и прямо. Избегайте "переводческого" стиля: "对于 X 来说", "作为 X", "我们的".
Сообщения об ошибках: мягкие, но четкие. "无法保存修改" предпочтительнее, чем "保存修改失败了！".
Кнопки: сначала глагол, 2–4 иероглифа. "取消", "保存修改", "立即同步".
Всплывающие подсказки (Tooltips): полное короткое предложение. "复制链接到剪贴板".
Плейсхолдеры: в стиле примера. "输入 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 — пример реализации переключателя языков.

Обновление этой страницы

Если вы изменяете какое-либо правило здесь, также:

Примените его в соответствующих файлах локалей JSON / CLAUDE.md / страницах документации.
Отметьте изменение в описании PR, чтобы рецензенты знали, на какие сопутствующие изменения стоит обратить внимание.

Эта страница является основным соглашением; ничто другое не имеет над ней приоритета.

Соглашения (Conventions)

On this page