Ui Microcopy

---
name: ui-microcopy
description: "UI 文案——写和改界面上的字：按钮、空状态、错误提示、确认弹窗、加载与成功反馈、表单标签与占位符，附中英对照。当用户说「这个报错怎么写」「按钮文案帮我改改」「空状态写什么」时使用。"
author: Captain
version: 0.1.1
display_name: "UI 文案"
display_name_en: "UI Microcopy"
description_zh: "界面文案怎么写：按钮、空状态、错误提示、确认弹窗、加载与成功反馈、表单标签与占位符。三条原则——说明后果、给下一步、别让用户猜；每类给模板、中英对照与反例，交付前过一遍 20 条自查清单。"
description_en: "Write and fix interface text (buttons, empty states, error messages, confirmation dialogs, loading and success feedback, form labels and placeholders) with Chinese-English pairs and a 20-point checklist."
tags:
  - "UI文案"
  - "界面文案"
  - "微文案"
  - "microcopy"
  - "UX writing"
  - "错误提示"
  - "按钮文案"
  - "空状态"
  - "表单文案"
  - "中英对照"
examples_zh:
  - "这个报错怎么写？用户上传超过 20MB 的文件时要提示"
  - "按钮文案帮我改改，删除弹窗里现在是「确定」和「取消」"
  - "空状态写什么？新用户第一次进来，项目列表是空的"
examples_en:
  - "How should this error read? Users who upload a file over 20 MB need a message"
  - "Fix my button labels: the delete dialog currently says OK and Cancel"
  - "What goes on the empty state? A new user's project list is empty on their first visit"
---

# UI 文案

定位一句话：**界面上的每一句字都在回答用户此刻的一个问题；答不上那个问题的文案，写得再顺也是噪音。**

## 何时使用

在对话里直接说要写或要改哪里的文案就行，不用记命令；扫描存量文案的脚本由助手在需要时运行。典型说法：

- 「这个报错怎么写？」
- 「按钮文案帮我改改」
- 「空状态写什么？」
- 「删除确认弹窗怎么写，才能说清楚又不吓人」
- 「这批文案出个英文版」
- 「上线前帮我把全产品的用词统一一下」

适用：新写或改写按钮、空状态、报错、弹窗、加载与成功提示、表单文字；要出中英双语版；上线前统一全产品用词。

给得越全越快：页面或位置、触发时刻（用户刚做了什么）、现有文案（没有就写「新写」）、相关产品规则（上限、保留天数、能否恢复）。存量文案在文件里的，给目录或文件路径即可。

不适用（遇到时这样处理）：

- 用户协议、隐私政策、免责声明等法律文本，或判断文案是否合规 → 交给法务；界面上指向这些文本的链接和按钮可以写。
- 中文、英文以外的本地化 → 请找专业译者与母语审校。
- 广告语、品牌口号、营销长文案 → 交给营销文案类技能；本技能只处理界面上的功能性文字。

## 先判断：用户此刻在问什么

```
按钮      点了会发生什么？  → 动词 + 对象：「保存草稿」「发送邀请」
空状态    为什么是空的？我能做什么？  → 原因 + 一个能点的下一步
错误提示  出了什么事？怪我吗？怎么办？  → 发生了什么 + 怎么解决，不怪用户
确认弹窗  能撤回吗？会失去什么？  → 具体动作 + 后果 + 与动作同名的按钮
加载      还在动吗？要等多久？  → 正在做什么；等得久就给进度
成功反馈  成了吗？结果在哪？  → 结果 + 去哪看或下一步
表单      填什么？什么格式？为什么要？  → 常驻标签 + 格式示例 + 用途说明
```

## 三条原则与写作步骤

**说明后果**：点下去之前就知道会怎样。**给下一步**：任何提示都不是死路。**别让用户猜**：不用「操作」「异常」「非法」这类系统视角的词。

```
1 写场景    谁、在哪个页面、刚做了什么、此刻的状态（着急 / 第一次用 / 刚出错）
2 写问题    把上表对应的问题写成一句话，文案必须正面回答它
3 写中文    动词开头，一句只说一件事；时限、上限、能否恢复等事实从产品规则取，拿不到写【待确认】
4 写英文    不逐字翻译，按英文界面习惯重写；按钮大小写（句首大写或每词大写）全产品只用一种
5 放进界面  在最窄屏幕、最长语言下看会不会截断；英文通常比中文长，按钮和标签留余量
```

## 六类文案：公式与正例

每类的完整模板、中英对照和反例见 [references/six-types.md](references/six-types.md)。速查：

| 类型 | 公式 | 正例（中 / English） |
|---|---|---|
| 按钮 | 动词 + 对象 | 保存草稿 / Save draft |
| 空状态 | 原因 + 一个能点的下一步 | 还没有项目。新建一个，邀请同事一起编辑。[新建项目] / No projects yet. Create one and invite your team to edit it together. [New project] |
| 错误提示 | 发生了什么 +（能说的话）为什么 + 怎么办；已填内容保留 | 文件超过 20 MB，无法上传。压缩后重试，或拆成几个小文件。/ This file is larger than 20 MB. Compress it or split it into smaller files, then try again. |
| 确认弹窗 | 具体动作 + 后果 + 与动作同名的按钮 | 删除「年度预算」？… [删除] [取消] / Delete "Annual budget"? … [Delete] [Cancel] |
| 加载与成功 | 正在做什么；结果 + 去哪看 | 正在导入… / Importing…；已发送给小王，可在「已发送」中查看。/ Sent to Xiao Wang. You can find it in Sent. |
| 表单 | 常驻标签 + 格式示例 + 用途说明 | 手机号；例：138 0000 0000；仅用于接收验证码，不会公开 / Phone number; e.g., 138 0000 0000; Only used for verification codes. Never shown publicly. |

能撤销的操作不弹确认，直接执行并给「撤销 / Undo」；确认弹窗留给不可逆、或会影响别人的动作。

## 20 条自查清单与存量扫描

交付前过一遍 20 条自查清单（按钮 4 条、空状态 3 条、错误 4 条、弹窗 3 条、反馈 2 条、表单 2 条、通用 2 条），全文见 [references/checklist-20.md](references/checklist-20.md)。

改存量文案时，先用脚本把典型坏句捞出来，每条命中都标出对应的自查条目号（locales/ 换成放文案的目录；python3 标准库，只读不改）：

```bash
python3 scripts/copy_lint.py locales/                       # 默认扫 json/yaml/properties/strings/po/xml/ts/js/vue/md 等
python3 scripts/copy_lint.py locales/ --ext .json,.yaml     # 只扫这些扩展名；--ext all 不限
python3 scripts/copy_lint.py src/i18n/zh-CN.json --json     # 单个文件，输出 JSON
```

## 信息不全或出错时

| 情况 | 怎么处理 | 对用户说的话（模板） |
|---|---|---|
| 缺关键信息（位置、触发时刻、产品规则） | 最多问 3 个：在哪个页面、什么时候出现？用户刚做了什么？涉及的上限、天数、能否恢复？其余按默认（语气克制、英文句首大写）先写，并标【待确认】 | 「先按克制语气写了两版，有两处【待确认】：文件上限是多少？删除后几天内能恢复？」 |
| 输入自相矛盾（同一动作一处叫删除、一处叫移除；弹窗说能恢复，规则说不能） | 列出矛盾的两处，给两种统一方案让用户选 | 「列表里叫"移除"，弹窗里叫"删除"。只是从列表拿掉、数据还在，就统一用"移除"；数据会删掉，就统一用"删除"。按哪种？」 |
| 事实拿不到（上限、保留天数、到账时间） | 不替产品编规则，写【待确认】，交付表里标「出处缺失」 | 「"30 天内可恢复"的天数要产品确认，先写成【待确认：保留天数】。」 |
| 超出本技能范围（法律文本、合规判断、其他语种、营销文案） | 说明该交给谁，界面上相关的按钮和链接文字照写 | 「隐私政策正文请交给法务；界面上"查看隐私政策"这个入口文案我来写。」 |
| 时间紧，只要最小可用版 | 最小版：只交中文、English 两列和「回答了哪个问题」一列；第二版和完整自查省略，只保留第 2、9、19 条三条硬检查 | 「最小版先给中英各一句，过了三条硬检查：危险按钮写动作、不怪用户、没有零信息句。」 |
| 用户坚持越界（羞辱式拒绝按钮、虚假倒计时、把取消订阅藏起来） | 不写，给不操纵用户的替代写法 | 「"不了，我不想省钱"这类按钮我不写；可以用"暂不需要"，同时把优惠内容写清楚。」 |

**脚本退出码与报错**

| 退出码 / 报错 | 原因 | 修正办法 |
|---|---|---|
| 0 | 没发现典型坏句 | 仍要按 20 条清单人工过一遍，脚本只覆盖其中几条 |
| 3 | 发现需要改的文案 | 按提示的自查条目改；命中不等于一定错，先看上下文 |
| 1（参数错误） | 没给路径，或 --ext 写成空 | 按 `python3 scripts/copy_lint.py locales/` 重跑 |
| 2（路径不存在 / 一个文件都没扫到） | 目录写错；扩展名不在默认列表；文件编码不是 UTF-8/GBK | 换成放文案的目录；加 `--ext all`；把文件转成 UTF-8 |
| 130 | 按了 Ctrl+C | 重跑即可；脚本只读，不会改动文件 |
| python3 用不了 | 本机没有 Python 3 | 用 references/checklist-20.md 末尾的 grep 命令替代 |

## 输出契约

交付物按这个顺序，缺一段不算完成：

1. **交付表**：`位置 | 触发时刻 | 中文 | English | 回答了用户的哪个问题`。改稿时在最前加「原文」列，并逐条说改了什么、为什么，不整段重写。
2. **关键文案双版本**：删除确认、付款按钮、报错给 2 个版本并说明差别，由用户选。
3. **事实出处**：上限、保留天数、能否恢复、多久到账逐条标出处；产品没定的写【待确认】，不替产品编规则。
4. **20 条自查结果**：哪几条没过、为什么；不适用的注明（最小版只报第 2、9、19 条）。
5. **需要你确认的点**：没有就写「无」。

占位符规则：`【待确认：保留天数】` 用于产品规则没定的事实；`【待补：错误原因】` 用于需要研发或产品提供的信息；动态内容用 `{项目名}`、`{n}` 这类变量写法。用全角【】而不用 [ ]，因为本技能里 [ ] 表示按钮，如 [新建项目]。

交付前自检（逐条答是/否，有「否」先改再交）：

- [ ] 每条文案都填了「回答了用户的哪个问题」，而且确实回答了？
- [ ] 危险操作的按钮写的是动作（删除、移除），不是「确定」？
- [ ] 没有「操作成功」「系统异常」「请稍后再试」「非法」这类零信息或责怪用户的词？
- [ ] 上限、天数等事实都有出处，没有的标了【待确认】？
- [ ] 英文按英文界面习惯重写，大小写全产品一致，最窄屏不截断？
- [ ] 改存量文案时跑过 copy_lint.py，退出码为 0 或每条命中都判断过？

## 示例

**示例（虚构场景）**：用户说「按钮文案帮我改改，删除弹窗里现在是「确定」和「取消」」。

助手先问（一次三个）：① 删除的是什么？② 删除后能恢复吗、几天内？③ 会影响别人吗？

用户补充：「删的是项目，项目里的文件一起删；回收站保留 30 天；项目成员会失去访问。」

最终交付：

| 位置 | 触发时刻 | 原文 | 中文 | English | 回答了用户的哪个问题 |
|---|---|---|---|---|---|
| 弹窗标题 | 点「删除项目」后 | 确定要执行此操作吗？ | 删除「{项目名}」？ | Delete "{project name}"? | 我要删的是哪个？ |
| 弹窗正文 | 同上 | （无） | 项目里的 {n} 个文件会一起删除，成员将无法访问。30 天内可在回收站恢复。 | All {n} files in this project will be deleted, and members will lose access. You can restore it from Trash within 30 days. | 会失去什么？能撤回吗？ |
| 主按钮 | 同上 | 确定 | 删除 | Delete | 点了会发生什么？ |
| 次按钮 | 同上 | 取消 | 取消 | Cancel | 能不能反悔？ |

- 双版本：A 版主按钮「删除 / Delete」，简洁，标题已写明对象；B 版「删除项目 / Delete project」，更明确，适合弹窗里还有其他操作时。
- 事实出处：30 天、成员失去访问来自你给的产品规则；{n} 由程序填入。
- 20 条自查：第 2、4、12、13 条已过；第 14 条不适用（删除影响他人且要保留确认）；未过：无。
- 需要你确认的点：无。

更多示例：[examples/upload-error.md](examples/upload-error.md)（文件超限报错：中英两版、字段级提示与自查结果）、[examples/empty-state.md](examples/empty-state.md)（新用户首次进入的空状态与搜索无结果）。

## 常见问题（FAQ）

**Q：英文版能直接机翻吗？**
A：不逐字翻译，按英文界面习惯重写；大小写全产品统一一种；英文通常比中文长，按钮和标签要留余量，并在最窄屏检查截断。

**Q：报错里要不要写错误码？**
A：可以留给客服排查，但不能只有错误码；先写发生了什么、怎么办，错误码放在末尾。

**Q：删除一定要弹确认吗？**
A：能撤销的操作不弹确认，直接执行并给「撤销 / Undo」；确认弹窗留给不可逆、或会影响别人的动作。

**Q：语气要活泼还是克制？**
A：按团队的写作规范；没有规范时先问一句，默认克制。本技能不替团队定品牌语气。

**Q：占位符能不能代替标签？**
A：不能。占位符一输入就消失，格式要求只写在里面，用户填到一半就忘了；标签常驻，占位符只放示例。

**Q：脚本没报问题，是不是就没问题了？**
A：脚本只捞典型坏句，覆盖第 1、5、8、9、12、19 条；英文截断、事实出处等其余条目要人工按清单过。

**Q：能帮我审隐私政策弹窗吗？**
A：法律文本和合规判断交给法务；弹窗里的按钮、入口链接这类界面文字可以写。

## 常见错误（反模式）

| 错误做法 | 为什么错 | 正确做法 |
|---|---|---|
| 删除弹窗里写「确定 / OK」 | 用户不看正文就点，看不出点了会发生什么 | 主按钮重复标题里的动词：[删除] |
| 「暂无数据 / No data」 | 没说为什么是空的，也没给出路 | 原因 + 一个能点的下一步 |
| 报错只写「上传失败（错误码 413）」 | 用户不知道发生了什么、该怎么办 | 发生了什么 + 怎么办，错误码放末尾 |
| 「输入非法」「您输入有误」 | 责怪用户，还没说正确格式 | 说正确格式：请输入 11 位手机号 |
| 「确定要执行此操作吗？」 | 没说是什么动作、会失去什么 | 标题写具体动作和对象，正文说后果和能否撤回 |
| 「操作成功！」 | 没说成了什么、结果在哪 | 结果 + 去哪看：已发送给小王，可在「已发送」中查看 |
| 其实是付款却写「提交」 | 用户不知道点了就会扣钱 | 写出动作：支付 {金额} / Pay {amount} |
| 标签写成「请输入您的手机号码」，格式只写在占位符 | 占位符一输入就消失，格式要求跟着消失 | 标签用名词短语常驻，格式示例放占位符，要求写在说明里 |
| 英文逐字翻译 | 语序别扭，长度容易撑破按钮 | 按英文界面习惯重写，留长度余量 |
| 可撤销的操作也弹确认 | 用户养成不看就点的习惯，真危险时也照点 | 直接执行 + 撤销 |
| 替产品编上限、天数 | 文案写错就是对用户的错误承诺 | 标【待确认】，问产品 |

## 边界与不做什么

- 不写用户协议、隐私政策、免责声明等法律文本，也不判断文案是否合规，请交给法务。
- 不写操纵性文案：羞辱式拒绝按钮（「不了，我不想省钱」）、虚假倒计时、把「取消订阅」藏起来的措辞。
- 不替团队定品牌语气：活泼还是克制按团队的写作规范；没有规范时先问一句再写。
- 只做中文与英文；其他语言的本地化请找专业译者与母语审校。
- 不替代可用性测试：文案好坏，最终看真实用户能否不看帮助就完成任务。