docs-voice

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

React Docs Voice & Style

React文档语气与风格指南

Universal Rules

通用规则

Capitalize React terms when referring to the React concept in headings or as standalone concepts:
- Core: Hook, Effect, State, Context, Ref, Component, Fragment
- Concurrent: Transition, Action, Suspense
- Server: Server Component, Client Component, Server Function, Server Action
- Patterns: Error Boundary
- Canary: Activity, View Transition, Transition Type
- In prose: Use lowercase when paired with descriptors: "state variable", "state updates", "event handler". Capitalize when the concept stands alone or in headings: "State is isolated and private"
- General usage stays lowercase: "the page transitions", "takes an action"
Product names: ESLint, TypeScript, JavaScript, Next.js (not lowercase)
Bold for key concepts: state variable, event handler
Italics for new terms being defined: event handlers
Inline code for APIs:
```
useState
```
,
```
startTransition
```
,
```
<Suspense>
```
Avoid: "simple", "easy", "just", time estimates
Frame differences as "capabilities" not "advantages/disadvantages"
Avoid passive voice and jargon

React相关术语大写规则：在标题中或作为独立概念指代React相关概念时，首字母大写：
- 核心概念：Hook、Effect、State、Context、Ref、Component、Fragment
- 并发概念：Transition、Action、Suspense
- 服务端概念：Server Component、Client Component、Server Function、Server Action
- 设计模式：Error Boundary
- 预览版概念：Activity、View Transition、Transition Type
- 散文语境：与描述词搭配使用时小写，例如："state variable"（状态变量）、"state updates"（状态更新）、"event handler"（事件处理器）。当概念独立出现或在标题中时大写："State是隔离且私有的"
- 通用用法保持小写："页面transitions（过渡）"、"执行一个action（操作）"
产品名称：ESLint、TypeScript、JavaScript、Next.js（请勿小写）
加粗用于关键概念：state variable、event handler
斜体用于定义新术语：event handlers
行内代码用于API：
```
useState
```
、
```
startTransition
```
、
```
<Suspense>
```
需避免的表述："简单的"、"容易的"、"只需"、时间预估类词汇
将差异描述为"能力"而非"优势/劣势"
避免被动语态和行话

Tone by Page Type

按页面类型划分的语气规范

Type	Tone	Example
Learn	Conversational	"Here's what that looks like...", "You might be wondering..."
Reference	Technical	"Call `useState` at the top level...", "This Hook returns..."
Blog	Accurate	Focus on facts, not marketing

Note: Pitfall and DeepDive components can use slightly more conversational phrasing ("You might wonder...", "It might be tempting...") even in Reference pages, since they're explanatory asides.

类型	语气	示例
学习类	口语化、通俗易懂	"下面是具体示例..."、"你可能会疑惑..."
参考类	技术严谨	"在顶层调用 `useState` ..."、"该Hook返回..."
博客类	准确客观	聚焦事实，避免营销话术

注意：即使在参考类页面中，Pitfall（陷阱）和DeepDive（深度解析）模块可使用稍口语化的表述（例如："你可能会好奇..."、"你可能会忍不住..."），因为它们是解释性的补充内容。

Avoiding Jargon

避免使用行话

Pattern: Explain behavior first, then name it.

✅ "React waits until all code in event handlers runs before processing state updates. This is called batching."

❌ "React uses batching to process state updates atomically."

Terms to avoid or explain:

Jargon	Plain Language
atomic	all-or-nothing, batched together
idempotent	same inputs, same output
deterministic	predictable, same result every time
memoize	remember the result, skip recalculating
referentially transparent	(avoid - describe the behavior)
invariant	rule that must always be true
reify	(avoid - describe what's being created)

Allowed technical terms in Reference pages:

"stale closures" - standard JS/React term, can be used in Caveats
"stable identity" - React term for consistent object references across renders
"reactive" - React term for values that trigger re-renders when changed
These don't need explanation in Reference pages (readers are expected to know them)

Use established analogies sparingly—once when introducing a concept, not repeatedly:

Concept	Analogy
Components/React	Kitchen (components as cooks, React as waiter)
Render phases	Restaurant ordering (trigger/render/commit)
State batching	Waiter collecting full order before going to kitchen
State behavior	Snapshot/photograph in time
State storage	React storing state "on a shelf"
State purpose	Component's memory
Pure functions	Recipes (same ingredients → same dish)
Pure functions	Math formulas (y = 2x)
Props	Adjustable "knobs"
Children prop	"Hole" to be filled by parent
Keys	File names in a folder
Curly braces in JSX	"Window into JavaScript"
Declarative UI	Taxi driver (destination, not turn-by-turn)
Imperative UI	Turn-by-turn navigation
State structure	Database normalization
Refs	"Secret pocket" React doesn't track
Effects/Refs	"Escape hatch" from React
Context	CSS inheritance / "Teleportation"
Custom Hooks	Design system

规范：先解释行为，再给出术语名称。

✅ "React会等待事件处理器中的所有代码执行完毕后，再处理状态更新。这种机制被称为batching（批处理）。"

❌ "React使用batching（批处理）来原子化处理状态更新。"

需避免或需解释的行话：

行话	通俗表述
atomic	全有或全无，批量处理
idempotent	相同输入得到相同输出
deterministic	可预测，每次结果一致
memoize	记住结果，跳过重复计算
referentially transparent	（避免使用 - 直接描述行为）
invariant	必须始终遵守的规则
reify	（避免使用 - 直接描述创建的内容）

参考类页面中允许使用的技术术语：

"stale closures"（过时闭包）- JS/React标准术语，可在注意事项中使用
"stable identity"（稳定标识）- React术语，指跨渲染周期保持一致的对象引用
"reactive"（响应式）- React术语，指值变化时会触发重新渲染
这些术语在参考类页面中无需解释（默认读者已了解）

类比使用规范：仅在引入概念时使用一次，避免重复：

概念	类比
组件/React	厨房（组件是厨师，React是服务员）
渲染阶段	餐厅点餐流程（触发/渲染/提交）
状态批处理	服务员收集完整订单后再去厨房
状态行为	某一时刻的快照/照片
状态存储	React将状态"放在架子上"
状态用途	组件的记忆
纯函数	菜谱（相同食材→相同菜品）
纯函数	数学公式（y = 2x）
Props	可调节的"旋钮"
Children prop	父组件预留的"空位"
Keys	文件夹中的文件名
JSX中的大括号	"通往JavaScript的窗口"
声明式UI	出租车司机（只需告知目的地，无需指挥每一步）
命令式UI	逐向导航
状态结构	数据库规范化
Refs	React不追踪的"秘密口袋"
Effects/Refs	脱离React控制的"逃生舱"
Context	CSS继承 / "传送"
自定义Hooks	设计系统

Common Prose Patterns

常见散文格式

Wrong vs Right code:

mdx

\`\`\`js
// 🚩 Don't mutate state:
obj.x = 10;
\`\`\`

\`\`\`js
// ✅ Replace with new object:
setObj({ ...obj, x: 10 });
\`\`\`

Table comparisons:

mdx

| passing a function | calling a function |
| `onClick={handleClick}` | `onClick={handleClick()}` |

Linking:

mdx

[Read about state](/learn/state-a-components-memory)
[See `useState` reference](/reference/react/useState)

错误与正确代码示例：

mdx

\`\`\`js
// 🚩 请勿直接修改state：
obj.x = 10;
\`\`\`

\`\`\`js
// ✅ 替换为新对象：
setObj({ ...obj, x: 10 });
\`\`\`

表格对比示例：

mdx

| 传递函数 | 调用函数 |
| `onClick={handleClick}` | `onClick={handleClick()}` |

链接示例：

mdx

[了解state相关内容](/learn/state-a-components-memory)
[查看`useState`参考文档](/reference/react/useState)

Code Style

代码风格

Prefer JSX over createElement
Use const/let, never var
Prefer named function declarations for top-level functions
Arrow functions for callbacks that need
```
this
```
preservation

优先使用JSX而非createElement
使用const/let，禁止使用var
顶层函数优先使用具名函数声明
需要保留
```
this
```
的回调函数使用箭头函数

Version Documentation

版本相关文档规范

When APIs change between versions:

mdx

Starting in React 19, render `<Context>` as a provider:
\`\`\`js
<SomeContext value={value}>{children}</SomeContext>
\`\`\`

In older versions:
\`\`\`js
<SomeContext.Provider value={value}>{children}</SomeContext.Provider>
\`\`\`

Patterns:

"Starting in React 19..." for new APIs
"In older versions of React..." for legacy patterns

当API在不同版本间发生变化时：

mdx

从React 19开始，直接渲染`<Context>`作为提供者：
\`\`\`js
<SomeContext value={value}>{children}</SomeContext>
\`\`\`

在旧版本中：
\`\`\`js
<SomeContext.Provider value={value}>{children}</SomeContext.Provider>
\`\`\`

表述规范：

新API使用"从React X版本开始..."
旧模式使用"在React旧版本中..."