Back to Details

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

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

TypeToneExample
LearnConversational"Here's what that looks like...", "You might be wondering..."
ReferenceTechnical"Call 
useState
at the top level...", "This Hook returns..."
BlogAccurateFocus 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:
JargonPlain Language
atomicall-or-nothing, batched together
idempotentsame inputs, same output
deterministicpredictable, same result every time
memoizeremember the result, skip recalculating
referentially transparent(avoid - describe the behavior)
invariantrule 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:
ConceptAnalogy
Components/ReactKitchen (components as cooks, React as waiter)
Render phasesRestaurant ordering (trigger/render/commit)
State batchingWaiter collecting full order before going to kitchen
State behaviorSnapshot/photograph in time
State storageReact storing state "on a shelf"
State purposeComponent's memory
Pure functionsRecipes (same ingredients → same dish)
Pure functionsMath formulas (y = 2x)
PropsAdjustable "knobs"
Children prop"Hole" to be filled by parent
KeysFile names in a folder
Curly braces in JSX"Window into JavaScript"
Declarative UITaxi driver (destination, not turn-by-turn)
Imperative UITurn-by-turn navigation
State structureDatabase normalization
Refs"Secret pocket" React doesn't track
Effects/Refs"Escape hatch" from React
ContextCSS inheritance / "Teleportation"
Custom HooksDesign 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逐向导航
状态结构数据库规范化
RefsReact不追踪的"秘密口袋"
Effects/Refs脱离React控制的"逃生舱"
ContextCSS继承 / "传送"
自定义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旧版本中..."