Skip to content

Use one set of terms across the console and docs - #701

Merged
SaladDay merged 8 commits into
mainfrom
align-console-terminology
Oct 14, 2026
Merged

SaladDay merged 8 commits into
mainfrom
align-console-terminology

Conversation

@SaladDay

@SaladDay SaladDay commented Oct 14, 2026 •

Copy link
Copy Markdown
Collaborator

What

This is Part 1 of UX polish lane E: one set of terms across the console and the docs.

  • Glossary. Both languages use "Harness"; English always capitalises it. English uses "Core key", "API key", "project API key" and "Environment templates". Chinese uses "Core 密钥", "API 密钥" and "项目 API 密钥". The zh leftovers are fixed: "API key", "API Keys", 凭证, 令牌 for usage, and 运行引擎. The Sandbox setup hint now reads "Console → API keys" / "控制台 → API 密钥".
  • One zh word per concept. The zh console and the zh docs now share one term for each concept:
    • Providers are 提供商: 沙箱提供商 for the Sandbox Provider (so "Provider not ready" reads 沙箱提供商未就绪) and 模型提供商 for the model provider. 模型服务, 沙箱后端, 服务商 and 提供方 are gone.
    • Project keys are 项目 API 密钥 everywhere, and projects are 项目 in zh prose.
    • Runtime stays "Runtime", e.g. "Runtime 历史" and "托管 Runtime". 运行时 remains only in 运行时长 and the Go runtime sentence.
    • Session, Item, Environment, Harness and Agent stay in English; templates are 模板 ("Environment 模板"), sub-agents are 子 Agent.
    • Usage counts are "token"; 凭据 replaces 凭证; 执行器凭据 is used for executor credentials; 主机 replaces 宿主机.
    • Mechanical replacements no longer leave spaces between Chinese words, e.g. 正在加载执行器凭据….
  • Empty states. Every state that means "nothing exists yet" now reads "No … yet" / "还没有…": keys ("No keys yet" / 还没有密钥), write operations, Vault Credentials, hosted sandboxes, node allocations, nodes, provider records and Item results. Filter results keep their own wording.
  • Dead code. legacyHashes is gone from lib/console-routes.ts, along with its test cases. Old hashes such as #builder, #playground and #api-keys now open the Overview. Copy with no caller is deleted: 423 keys, including 58 unused zh sandbox entries, plus the unused dashboard namespace. The unused Vault catalog helpers (agentNeedsCredentialCatalog, deriveSessionVaultPlan, loadVaultCatalog, matchingCredentials) are deleted with their tests, their error copy and the top-level collection pager only they used.
  • Docs.
    • English and zh docs capitalise Harness, as do the site tagline and apps/web/.impeccable notes.
    • zh docs name pages and actions exactly as the zh console does, e.g. 设置 → 沙箱与调度 → 保存配置, 项目与密钥 → 签发密钥, 节点 → 添加节点. The reviewer's label checker now also checks zh docs against the zh copy and reports no Web label (the four hits left are GitHub's Actions, the installer's own output, an API resource heading, and a Sandbox metrics line that Fix console leftovers from the UX review #702 rewrites).
    • zh docs use the terms above, drop the gloss headings such as "## Agents(智能体)", title Runtime observability "Runtime 可观测性", and say 原生 Harness in README.zh-CN.md. The zh site landing copy follows too.
    • contracts/agents-api/zh/sessions-events.md says Session and Item instead of 会话 and 条目.
    • Runtime observability uses "token" for usage.
    • zh source_hash values are refreshed for every changed English source.
    • apps/web/PRODUCT.md and the Plain Vocabulary Rule in apps/web/DESIGN.md record the decisions for the zh copy and the zh docs alike.

Why

The UX review found the same concept under two or three names, often on one screen, e.g. 运行时历史 next to Runtime 历史, and API key next to API 密钥. Docs and Web also named the same things differently. Unused copy made each sweep longer and hid real leftovers.

Verification

  • pnpm --filter @oac/web typecheck
  • vitest run across all of apps/web, because the pruned copy is shared: 71 files, 381 tests passed.
  • Playwright on every spec that asserts zh copy or the changed copy, run with the bundled Chromium instead of the chrome channel: diagnostics, overview-readiness, sandbox-generation, wording, sandbox-lifecycle, sandbox-reset, sandbox-rollout-details, resources and access, 49 passed. Earlier round: nodes, resources and provider-observations, 18 passed.
  • pnpm --dir website check-translations, make check-docs and make check-names.
  • The label checker with --zh over the zh docs.
  • Fixture screenshots in zh and en at 1440 and 390 px: Overview, Sandbox metrics, Nodes, Projects and keys, Settings → Models and credentials, Session log and Environment templates.

Skipped

  • Full make check, per lane rules.
  • The other Playwright specs.
  • Go checks, because no Go code changed.
  • Mermaid diagram labels in the zh docs stay in English, as in every zh diagram.

Merging with #702

Whichever of #701 and #702 merges second gets small conflicts with adjacent lines: apps/web/PRODUCT.md (Terminology line), apps/web/e2e/diagnostics.spec.ts:57, en/sessions.ts and zh-CN/sessions.ts, and docs/zh/web/index.md (its source_hash and the Sandbox metrics row). Resolve each by keeping #702's structure (its locators, Status copy, Sandbox metrics row and source_hash) and #701's terms (e.g. 模型提供商认证失败, the Terminology line).

Providers are 提供商 (沙箱提供商, 模型提供商), Environment stays an API
term, templates are 模板, and stray spaces between Chinese words are gone.
The Plain Vocabulary Rule in DESIGN.md and PRODUCT.md now names these
terms for the zh copy and the zh docs alike.
Nothing outside their own tests called agentNeedsCredentialCatalog,
deriveSessionVaultPlan, loadVaultCatalog or matchingCredentials, so they
go with their tests, the error copy only they used, and the top-level
collection pager only the catalog needed.
The zh docs now name pages and actions exactly as the zh console does,
call project keys 项目 API 密钥, and use 项目, 沙箱提供商, 模型提供商,
提供商, 模板, 主机 and 子 Agent throughout, without gloss headings or
stray spaces.
@SaladDay
SaladDay merged commit ccc0ac8 into main Oct 14, 2026
17 checks passed
@SaladDay
SaladDay deleted the align-console-terminology branch October 14, 2026 10:04
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant