better-writing

文案

这项技能用于编写和审查界面文案，例如标签、错误提示、空状态和确认信息，以及贯穿其中的术语。它会沿用产品现有的语气，并标出可能误导用户或没有提供后续操作途径的文案。

鲜明的品牌语气并非缺陷。只有当偏离通俗表达造成不一致、歧义、翻译风险，或与情境的重要程度不相称时，才应指出。仅仅因为改写后的文案更合个人喜好，并不构成问题。

文案的呈现方式，包括 text-transform、截断和智能标点，属于 better-typography。错误标记、播报内容以及承载可访问名称的属性属于 better-accessibility。为翻译后的字符串留出空间属于 better-layout。

先盘点现有字符串

开始编写或审查之前，先找到文案所在的位置，并阅读修改内容周边的文案：

1. 搜索翻译调用（t(、i18n.、<FormattedMessage、$t(）及其读取的语言区域文件，例如 locales/**/*.json、messages/*.json、*.po 和 *.strings。文案也可能来自 CMS 或 API。
2. 列出每种对象所用的名词，以及每种操作所用的动词，例如“项目”或“工作区”，以及“删除”或“移除”。
3. 记录各类元素使用的大小写形式，以及任何语气或内容风格指南。

新文案应使用清单中的术语。只有同一事物被称作两个不同名称时，同义词才构成问题。

统一语气，统一词汇

产品只有一种语气，其现有文案已经确立了这种语气。局部修改不能另创一种语气。如果菜单中用的是“归档”，提示消息中就不应写成“移至存储区”。

多步骤流程应始终使用同一套词汇：“开始使用”用于进入流程，“继续”或“下一步”用于推进，“完成”用于结束。语气应根据情境的重要程度调整：

情境	语气
成功、引导、空状态	亲切，可以轻松一些
常规操作、设置	中性、简洁
错误、破坏性操作确认	冷静、直白，不带玩笑意味
数据丢失、安全	严肃、明确

直接对读者说话

在说明性文案中，写“你”，不要写“用户”。在错误提示中，“我们”听起来像是在推卸责任，因此更适合写“无法加载内容。请检查网络连接，然后重试。”在风险较低的文案中，如果既有的第一人称表达仍然清晰，就可以保留。

谨慎使用所有格：“收藏”优于“你的收藏”。不要在同一流程中混用不同视角，例如在“我的账户”旁边写“你的设置”。

用浅显的词，避免花哨表达

选择让疲惫的读者一眼就能理解的词，并删掉所有没有实际作用的词。不要使用成语、口语化表达或无法翻译的幽默。

避免不必要的性别表述：写“订阅者可以发布食谱”，不要写“每位订阅者都可以发布他或她的食谱”。文案应匹配输入设备：触屏操作用“轻触”，指针操作用“单击”，两种方式都适用时用“选择”。

完整编写字符串

不要通过变量拼接句子片段（"You have " + n + " new messages"），因为不同语言的语序各不相同。应将整句话写成一条带占位符的消息，并使用语言区域的复数规则，而不是使用 n === 1 ? "" : "s"。许多语言的复数形式不止两种。请通过 Intl 格式化数字、日期和列表。请参阅 patterns.md 中的示例。

按动词优先编写按钮文案

按钮标签应以表示操作的动词开头：“发送”“保存草稿”“删除项目”。不要写“好的！”或“开始吧！”

仅含图标的按钮，其可访问名称也应遵循同一规则。名称应描述操作，例如“删除项目”，而不是描述图形，例如“垃圾桶图标”。承载该名称的属性归 better-accessibility 管理。

链接应描述其目标

即使脱离上下文，链接文字也应清晰易懂，因为屏幕阅读器用户会通过页面链接列表进行导航。写“阅读账单文档”，不要写“点击这里”。

同一页面上出现两个“了解更多”时，意思就不明确了。请为每个链接添加具体主题：“了解更多导出相关信息”。

统一大小写规则

为每种元素类型选择标题式大小写或句首字母大写，然后在所有同类元素中保持一致。如果项目没有规定，默认使用句首字母大写。「Save Changes」和「Discard changes」并列，看起来就很不严谨。

设置项描述开启状态

切换开关的标签应描述开启时会发生什么。「发送已读回执」能让用户推断关闭时的状态；「不要发送已读回执」则会让开关变成双重否定。

直接链接到所提及的设置项，而不是描述前往该设置项的路径：使用「通知设置」链接，而不是「前往设置 > 通知 > 电子邮件」。

错误提示说明修复方法，并紧邻出错位置

错误提示是一条操作指引，应放在出错的字段旁边：

不佳	更好
密码太短	请选择至少包含 8 个字符的密码
日期无效	请按 DD/MM/YYYY 格式输入日期
哎呀！出错了。	无法保存。请检查网络连接并重试。

不要责怪用户，不要说「哎呀」，也不要使用感叹号。提示应采用积极的表述，例如「至少使用 8 个字符」，而不是「不要少于 8 个字符」。对于已知要求，应在用户输入前以辅助文本说明，而不是只在出错时提示。如果同一种错误反复出现，就重新设计交互，让这种错误无法发生。

优先提供撤销，而非确认

如果操作可以撤销且用户经常执行，例如归档、移动或删除到回收站，应优先提供撤销。立即执行操作，并在结果中提供撤销选项：「项目已归档。撤销」。

如果操作无法撤销、会影响他人或会一次性销毁大量项目，则应在执行前确认。确认内容应重述后果，让用户无需阅读正文也能回答：

• 标题应写明操作和对象，例如「删除‘Q3 report’？」，绝不能写「确定吗？」。
• 正文应说明会丢失什么，以及哪些内容无法恢复；适用时注明数量。
• 按钮应使用「动词 + 对象」的形式，例如 Delete project 和 Cancel，绝不能用 Yes 和 No。
• 对于账户、工作区或代码仓库，应要求用户输入对象名称。

模板见 patterns.md。破坏性按钮应使用与众不同的颜色 better-colors。

空状态指明下一步

空状态应说明此处的用途、如何填充内容，并提供一个明确的下一步操作：

<p>No results.</p>


<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>

筛选结果为空时，应指出查询内容并提供退出方式：「没有找到与‘quarterly’相关的结果。清除筛选条件」。不要在空状态中放置持久信息，因为一旦有了内容，这些信息就会消失。

加载、保存和成功提示文案见 patterns.md。

占位符提供示例

占位符应展示符合字段格式的真实示例，例如 [email protected] 或 DD/MM/YYYY，绝不能写操作指引。字段是否还需要可见标签，参见 better-accessibility。

完成之前

检测模式	修复方法
Click here、文字为 here 的链接，或两个相同的 Learn more 链接	写明目标位置
错误字符串中出现 Oops、Something went wrong 或 !	说明出错内容和下一步操作
" + n + "、包含句子片段的模板字面量，或 === 1 ? "" : "s"	使用一个带复数参数的 ICU 消息
对话框按钮上的 >OK<、>Yes< 或 >No<	使用「动词 + 对象」的形式
Are you sure	写明操作和对象
successfully	删除，改为「更改已保存」
常规操作指引中的 Please	删除
以 Don't、Disable 或 Hide 开头的开关标签	描述开启状态
aria-label="Trash"、"Close icon" 或 "X"	写明操作：「删除项目」「关闭对话框」
未指定区域设置的 toLocaleDateString()，或使用 getMonth() 构造的日期	使用 Intl.DateTimeFormat 并传入用户的区域设置
Save Changes 和 Discard changes 并列	同类元素使用统一的大小写规则

报告

严重程度。 HIGH 会误导用户，或隐瞒如何从错误中恢复。未说明恢复方法的错误始终属于 HIGH；未确认且无法撤销的破坏性操作也属于 HIGH。MEDIUM 会破坏语气、术语或大小写的一致性。LOW 是个别措辞润色问题。

验证。 检查每个标签是否与其触发的操作相符、每条错误信息是否说明了解决方法，以及每个术语是否符合术语清单。除了组件，也要阅读本地化文件。对于无法查看、由服务器或 CMS 提供的字符串，请报告为 Not verified。

格式。 按违反的原则对发现的问题分组，按严重程度排序；每个根本原因占一行，并列出其出现的所有位置：

Severity	Location	Before	After	Why

Location 格式为 path/to/file:line。Why 需指出相关原则和对用户的影响。

只要仍有 HIGH 问题，结尾就写 Block；否则写 Approve，并将其余问题留在表格中作为待办事项。切勿对未检查的内容宣布 Approve。若没有需要报告的问题，请写“没有需要采取行动的文案问题”，并报告验证情况。