better-writing

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Writing that disappears into the interface

让文案隐于界面

Clear and brief beats clever, consistency beats variety, and the best error message is the interaction redesigned so the error can't happen. Apply these principles when writing or reviewing any user-facing text.

How copy renders (capitalization via

text-transform

, truncation, smart punctuation) is covered by the

better-typography

skill; error markup and announcements (

aria-invalid

, live regions) by the

better-accessibility

skill; room for translated strings by the

better-layout

skill.

清晰简洁优于花哨巧思，一致性优于多样性，最佳的错误提示是重新设计交互以避免错误发生。撰写或审核任何面向用户的文本时，请遵循这些原则。

文案的渲染方式（通过

text-transform

设置大小写、截断处理、智能标点）由

better-typography

技能覆盖；错误标记与播报（

aria-invalid

、实时区域）由

better-accessibility

技能覆盖；为翻译字符串预留空间由

better-layout

技能覆盖。

Core Principles

核心原则

1. One Voice, Flexible Tone

1. 统一语态，灵活语调

The product has one voice: plain, direct, consistent terms for the same things. Keep a shared term list so the same action never has two names: if it's "Archive" in the menu, it isn't "Move to storage" in the toast. Tone flexes with the stakes:

Context	Tone
Success, onboarding, empty states	Warm, can be light
Routine actions, settings	Neutral, minimal
Errors, destructive confirmations	Calm, plain, zero playfulness
Data loss, security	Serious, explicit

产品需保持统一的语态：直白、直接，同一事物使用一致术语。维护共享术语列表，确保同一操作不会有两种名称：若菜单中是“Archive”（归档），则提示框中不能是“Move to storage”（移至存储）。语调可根据场景风险灵活调整：

场景	语调
成功提示、引导流程、空状态	亲切温和，可略带轻松感
常规操作、设置项	中立客观，简洁明了
错误提示、破坏性操作确认	冷静直白，零戏谑感
数据丢失、安全相关	严肃正式，表述明确

2. Say "You", Never "The User"

2. 用“你”称呼用户，绝不用“用户”

Address the reader directly as "you". Avoid "we": it's ambiguous, and in errors it reads as deflection. "Unable to load content", not "We're having trouble loading this content". Use possessives sparingly ("Favorites" over "Your Favorites") and never switch perspective mid-app.

直接以“你”称呼读者。避免使用“我们”：表述模糊，且在错误提示中会显得推诿。例如：“无法加载内容”，而非“我们加载此内容时遇到问题”。谨慎使用所有格（用“收藏”而非“你的收藏”），且整个应用中不要切换视角。

3. Plain Words Over Clever Ones

3. 直白用词优于花哨表达

Choose easily understood words and delete every word that isn't needed. No idioms, colloquialisms, or humor that won't translate. Skip unnecessary gender: "Subscribers can post recipes", not "each subscriber can post his or her recipes". Match the input device: "tap" on touch, "click" with a pointer, "select" when both are possible. Never build sentences by concatenating fragments around variables (

"You have " + n + " new messages"

); word order changes per language, so use full templated strings with proper pluralization.

选择易于理解的词汇，删除所有非必要的词。避免使用习语、口语化表达或无法翻译的幽默内容。避免不必要的性别指代：“订阅者可发布食谱”，而非“每位订阅者可发布他或她的食谱”。匹配输入设备：触屏设备用“轻点”，指针设备用“点击”，两种设备都适用时用“选择”。切勿通过拼接片段与变量构建句子（如

"You have " + n + " new messages"

）；不同语言的语序不同，请使用带有正确复数形式的完整模板字符串。

4. Verb-First Buttons

4. 按钮标签以动词开头

Button labels start with a verb naming the specific action: "Send", "Save draft", "Delete project". Never "OK!", "Let's go!", or bare "Yes"/"No" on consequential actions. Confirmation buttons repeat the consequence so the dialog is answerable without reading the body: "Delete this project?" offers

Delete project

and

Cancel

, not

Yes

and

No

按钮标签以动词开头，明确具体操作：“发送”、“保存草稿”、“删除项目”。对于有重大影响的操作，绝不要用“OK!”、“出发!”或单纯的“是”/“否”。确认按钮需重复操作后果，使用户无需阅读对话框正文即可做出选择：例如“删除此项目？”应提供

Delete project

（删除项目）和

Cancel

（取消）选项，而非“是”和“否”。

5. Consistent Flow Vocabulary

5. 流程词汇保持一致

Multi-step flows use one vocabulary: "Get Started" to enter, "Continue" or "Next" (pick one) to advance, "Done" to finish. Alternating synonyms across steps makes users wonder if the buttons do different things.

多步骤流程使用统一词汇：用“开始”进入流程，用“继续”或“下一步”（二选一）推进流程，用“完成”结束流程。在不同步骤交替使用同义词会让用户怀疑按钮功能是否不同。

6. Links Describe Their Destination

6. 链接文本明确指向目标

Link text makes sense out of context; screen-reader users navigate by a list of the page's links. "Read the billing docs", never "Click here" (which also fails the device-verb rule on touch), and never a bare "Learn more" when several appear on one page. Suffix each: "Learn more about exports".

链接文本脱离上下文仍有意义；屏幕阅读器用户通过页面链接列表导航。例如“查看账单文档”，而非“点击此处”（这也不符合触屏设备的动词规则），同一页面有多个“了解更多”时，切勿使用无修饰的“了解更多”，需补充后缀：“了解更多导出相关内容”。

7. One Capitalization Policy

7. 统一大小写规则

Pick title case or sentence case per element type (all buttons, all headings) and apply it consistently; sentence case is the safer default: calmer, no per-word case rules, localizes cleanly. "Save Changes" beside "Discard changes" reads as sloppiness.

针对每种元素类型（所有按钮、所有标题）选择标题大小写或句子大小写，并保持一致；句子大小写是更安全的默认选项：更平和，无逐词大小写规则，本地化适配更顺畅。“Save Changes”（保存更改）与“Discard changes”（放弃更改）并列会显得不严谨。

8. Settings Describe the ON State

8. 设置项描述开启状态

Label a toggle for what happens when it's on: "Send read receipts", and users infer the off state. Never label the negative ("Don't send read receipts"), which turns the toggle into a double negative. Link directly to a referenced setting instead of describing the path to it: a "Notification settings" link, not "Go to Settings > Notifications > Email".

开关标签应描述开启后的效果：“发送已读回执”，用户可自行推断关闭状态。切勿用否定式描述（如“不发送已读回执”），否则会让开关变成双重否定。直接链接到相关设置项，而非描述路径：用“通知设置”链接，而非“前往设置 > 通知 > 邮件”。

9. Errors Say How to Fix, Next to Where It Broke

9. 错误提示说明解决方法，紧邻出错位置

An error is an instruction, adjacent to the failing field:

Bad	Good
That password is too short	Choose a password with at least 8 characters
Invalid name	Use only letters for your name
Oops! Something went wrong.	Unable to save. Check your connection and try again.

No blame, no "oops", no exclamation marks. Phrase hints positively ("Use only letters", not "Don't use numbers or symbols") and show them before the mistake, not after. If the same error keeps firing for many users, redesign the interaction instead of rewording it.

错误提示是操作指引，需紧邻出错字段：

错误示例	正确示例
密码太短	请选择至少8个字符的密码
无效姓名	姓名仅可使用字母
哎呀！出了点问题。	无法保存，请检查网络连接后重试。

不要指责用户，不要用“哎呀”，不要加感叹号。以正面表述给出提示（如“仅可使用字母”，而非“请勿使用数字或符号”），并在用户犯错前展示提示。如果大量用户反复遇到同一错误，应重新设计交互而非修改文案。

10. Empty States Point Forward

10. 空状态指引下一步操作

An empty state says what this place is and how to fill it, with one clear next action:

html

<!-- Bad: a shrug -->
<p>No results.</p>

<!-- Good: orientation plus a next step -->
<p class="font-medium">No projects yet</p>
<p class="text-sm text-zinc-500">Projects keep your tasks and files together.</p>
<button class="mt-4">Create a project</button>

Search and filter empty states name the query and offer an exit: "No results for 'quarterly'. Clear filters". Never park crucial persistent information in an empty state; it disappears the moment content exists.

空状态需说明当前区域用途及填充方式，并提供一个清晰的下一步操作：

html

<!-- 错误示例：仅表示无内容 -->
<p>No results.</p>

<!-- 正确示例：说明用途并提供下一步操作 -->
<p class="font-medium">暂无项目</p>
<p class="text-sm text-zinc-500">项目可将您的任务和文件集中管理。</p>
<button class="mt-4">创建项目</button>

搜索和过滤的空状态需说明查询内容并提供退出方式：“未找到‘季度’相关结果。清除筛选条件”。切勿将重要的持久信息放在空状态中；一旦有内容，这些信息就会消失。

11. Placeholders Are Examples, Not Labels

11. 占位符是示例，而非标签

Placeholders show the expected format (

name@example.com

DD/MM/YYYY

). A placeholder is never the field's only label: it vanishes on input, and every field keeps a visible label.

占位符展示预期格式（如

name@example.com

、

DD/MM/YYYY

）。占位符绝不能作为字段的唯一标签：输入时它会消失，每个字段都需保留可见标签。

Common Mistakes

常见错误

Mistake	Fix
"The user" in interface copy	Address the reader as "you"
"We're having trouble…" in an error	Drop the "we": "Unable to load content"
`OK` / `Yes` confirming a destructive dialog	Repeat the consequence: "Delete project"
"Continue" on step 2, "Next" on step 3	One flow vocabulary throughout
"Click here" or bare "Learn more" link	Describe the destination: "Read the billing docs"
"Save Changes" beside "Discard changes"	One capitalization policy per element type
"Don't send read receipts" toggle	Label the ON state: "Send read receipts"
"Oops! Something went wrong."	Say what to do, next to the failing field
"No results." as the whole empty state	Orient and point forward with a next action
Placeholder doing the label's job	Visible label; placeholder shows the format
`"You have " + n + " messages"`	Full templated strings with pluralization

错误	修正方案
界面文案中使用“用户”	直接称呼读者为“你”
错误提示中使用“我们遇到了…问题”	删除“我们”：“无法加载内容”
破坏性对话框中用“OK”/“是”确认	重复操作后果：“删除项目”
第二步用“继续”，第三步用“下一步”	全程使用统一的流程词汇
链接文本用“点击此处”或无修饰的“了解更多”	明确指向目标：“查看账单文档”
“Save Changes”与“Discard changes”并列	每种元素类型使用统一的大小写规则
开关标签用“不发送已读回执”	描述开启状态：“发送已读回执”
错误提示用“哎呀！出了点问题。”	在出错位置旁说明解决方法
空状态仅显示“无结果。”	说明用途并指引下一步操作
占位符承担标签的作用	保留可见标签；占位符仅展示格式
使用 `"You have " + n + " messages"`	使用带有复数形式的完整模板字符串

Review Output Format

审核输出格式

Present every review in two parts.

每份审核报告分为两部分。

Findings

问题发现

Group findings by principle. Use a markdown table with Severity, Location, Before, After, and Why columns. Include every change made or proposed, not a subset. Never use separate "Before:" / "After:" lines.

Severity:
```
HIGH
```
misleads users, obscures a consequence, or prevents recovery;
```
MEDIUM
```
makes a task harder to understand;
```
LOW
```
is isolated voice or consistency polish.
Location: cite
```
path/to/file:line
```
. If the artifact has no source files, cite the exact screen and component instead.
Before / After: quote the current copy and its complete replacement.
Why: name the violated principle and explain the comprehension or trust cost.

Consolidate a repeated systemic issue into one row and list every affected location. Omit principles with no findings.

按原则分组展示问题。使用包含严重程度、位置、修改前、修改后、原因列的markdown表格。列出所有已修改或建议修改的内容，而非部分内容。切勿使用单独的“修改前：”/“修改后：”行。

严重程度：
```
HIGH
```
（误导用户、掩盖后果或阻碍恢复）；
```
MEDIUM
```
（增加任务理解难度）；
```
LOW
```
（孤立的语态或一致性优化）。
位置：引用
```
文件路径:行号
```
。若工件无源文件，则引用具体页面和组件。
修改前/修改后：引用当前文案及其完整替换内容。
原因：指出违反的原则，并说明对理解或信任的影响。

将重复的系统性问题合并为一行，并列出所有受影响的位置。省略无问题的原则。

Example

示例

Errors say how to fix

错误提示需说明解决方法

Severity	Location	Before	After	Why
MEDIUM	`src/PasswordField.tsx:36`	"Invalid password"	"Choose a password with at least 8 characters"	The error must say how to fix the problem
HIGH	`src/Editor.tsx:81`	"We couldn't process your request" toast	Inline "Unable to save. Check your connection and try again."	The current message neither locates the failure nor offers recovery

严重程度	位置	修改前	修改后	原因
MEDIUM	`src/PasswordField.tsx:36`	"Invalid password"	"Choose a password with at least 8 characters"	错误提示必须说明解决方法
HIGH	`src/Editor.tsx:81`	"We couldn't process your request"提示框	内联提示"Unable to save. Check your connection and try again."	当前提示既未定位故障位置，也未提供恢复方案

Verb-first buttons

按钮标签以动词开头

Severity	Location	Before	After	Why
HIGH	`src/DeleteDialog.tsx:29`	"OK" on the delete confirmation	"Delete project"	A consequential action must repeat the consequence
MEDIUM	`src/Signup.tsx:54`	"Let's go!"	"Create account"	The label must name the action

严重程度	位置	修改前	修改后	原因
HIGH	`src/DeleteDialog.tsx:29`	删除确认对话框中的"OK"	"Delete project"	有重大影响的操作必须重复操作后果
MEDIUM	`src/Signup.tsx:54`	"Let's go!"	"Create account"	标签必须明确操作内容

Verification and Verdict

验证与结论

After the findings:

Verification: list the exact checks run and their observed results, including the complete flow, variable interpolation, pluralization, and narrow-width wrapping when applicable. If a check was not run, state what still needs verification.
Verdict:
```
Block
```
if any
```
HIGH
```
finding remains,
```
Needs changes
```
if only
```
MEDIUM
```
or
```
LOW
```
findings remain, and
```
Approve
```
only when no actionable findings remain.

When there are no findings, omit the tables, state "No actionable writing findings", report verification, and end with

Approve

问题发现之后：

验证：列出执行的具体检查及其结果，包括完整流程、变量插值、复数形式、窄宽度换行（如适用）。若未执行某项检查，说明仍需验证的内容。
结论：若仍有
```
HIGH
```
级问题，标记为
```
Block
```
（阻止通过）；若仅剩余
```
MEDIUM
```
或
```
LOW
```
级问题，标记为
```
Needs changes
```
（需要修改）；仅当无待处理问题时，标记为
```
Approve
```
（批准通过）。

若无问题发现，可省略表格，说明“无待处理的文案问题”，报告验证情况，最后标记为

Approve

。