前端CMS【免费下载链接】wp-calypsoThe JavaScript and API powered WordPress.com项目地址https://gitcode.com/gh_mirrors/wp/wp-calypso点击查看免费下载导读本文是 wp-calypso 仓库中 client/dashboard/docs/typography-and-copy.md 的深度解读与实践指南。该文档定义了新 Hosting Dashboard托管控制台中所有用户可见文案的统一标准涵盖美式英语拼写、标点、大小写规则以及 Snackbar 通知的成功/失败消息模板。读完本文你将掌握 wp-calypso 界面文案的完整书写规范理解每条规则背后的源码落地方式并能在为 Dashboard 编写或 review 文案时快速套用这套模板。一、文档定位Dashboard 文案的宪法在 wp-calypso 的 client/dashboard 目录下docs子目录集中存放着针对 Dashboard 开发的专项规范包括 i18n.md国际化、testing.md测试等而 typography-and-copy.md 负责的正是文案怎么写这件事——它不关心组件长什么样只关心用户在界面上读到的每一个字。它是一份面向开发者的直接约束任何在 Dashboard 中出现的新文案按钮、弹窗标题、表单标签、DataViews 字段标签、Snackbar 通知都应遵循其中的规则。文档本身结构清晰按通用规则 → 大小写 → Snackbar三层递进本文沿用这一骨架并补充仓库中的实际代码证据让每条规范都可落地、可验证。二、通用规则拼写、标点与引号原文档的 General 一节给出了三条最基础的书写准则它们适用于 Dashboard 中所有用户可见的文案。2.1 统一使用美式英语拼写Use US English spelling (e.g. customize not customise, color not colour).一律使用美式拼写customize而非customise、color而非colour、center而非centre。这条规则与项目整体的国际语言基调一致——Dashboard 的文案最终都要经过wordpress/i18n的__()函数走翻译流水线见 client/dashboard/docs/i18n.md英文原文的拼写统一能大幅降低翻译歧义。2.2 句号的使用规则按文案类型区分End sentences with a period. Even short ones. Button and form labels do not end in periods, and neither do headings.这是最容易混淆的一条规则分两面文案类型是否以句号结尾示例完整句子含 Snackbar 消息是必须加句号Defensive mode enabled.按钮标签Button labels否Save、Disable表单标签Form labels否Duration标题Headings含弹窗标题否Defensive mode is enabled原文档特别强调哪怕是短句也要加句号这是为了保持信息密度较高的操作反馈在视觉上完整、可读。仓库中的实际代码正是这样落地的例如 client/dashboard/sites/settings-defensive-mode/index.tsx 中的__( Defensive mode enabled. )以及 client/dashboard/domains/domain-dns/actions.tsx 中的__( DNS record deleted. )句号都完整保留。2.3 使用弯引号与弯撇号Use curly quotes and apostrophes. e.g. like this instead of like this, e.g. its instead of its引号使用弯引号curly quotes左引号“、右引号”。撇号使用弯撇号curly apostrophe’例如it’s而不是its。直引号straight quotes和直撇号仅应出现在代码上下文中用户可见文案一律使用弯形变体。这一规则在 client/dashboard/emails/dataviews/actions/edit-email-forward.tsx 中有直接体现错误消息Failed to update forwarder %(emailAddress)s with message “%(message)s”. ...中包裹用户消息的就是弯引号“”。三、大小写规范几乎一切使用 Sentence CaseRule of thumb: use sentence case for almost everything.核心原则是除了专有名词几乎全部使用句子大小写sentence case——即只有句首单词首字母大写其余单词一律小写专有名词除外绝不使用 Title Case每个单词都首字母大写。原文档点名了四类必须使用 sentence case 的文案按钮标签Button labels如Disable、Save settings首词大写、其余小写。弹窗标题Modal titles弹窗标题同样按句子大小写处理且按 2.2 的规则不加句号。表单标签Form labels例如 Defensive mode 设置页中的Duration见 client/dashboard/sites/settings-defensive-mode/index.tsx。DataViews 字段标签DataViews field labelsDashboard 大量使用wordpress/dataviews构建数据表格例如 client/dashboard/agency/earn/migrations/commissions-list/index.tsx 引入DataViews其列标题、筛选器标签等字段文案同样遵循 sentence case。3.1 唯一的专有名词例外Hosting DashboardTreat Hosting Dashboard like a proper noun. Capitalize it when referring to the product.当 Hosting Dashboard 作为产品名出现时必须视作专有名词两个词均大写。这一点在仓库中可找到对应证据client/dashboard/me/hosting-dashboard/index.tsx 中切换新托管控制台时的消息Failed to enable New Hosting Dashboard.与Failed to disable New Hosting Dashboard.其中 Hosting Dashboard 均保持了专有名词的大写形态。四、Snackbar 通知文案规范文档核心章节Snackbar也叫 flash message / toast是网络请求完成后弹出的轻量通知。原文档用最大篇幅规定了 Snackbar 的文案写法其核心思想是成功消息必须包含操作对象设置名并以过去式动词结尾错误消息必须以 Failed 开头。下面按原文档骨架逐条展开。4.1 成功消息按是否为开关型设置分两套模板当设置本身是或表现为一个**功能开关feature toggle**时——例如 SSH 访问、Defensive mode——成功消息使用开启/关闭模板{Setting name} enabled. {Setting name} disabled.当设置不是开关型即普通配置项保存时使用{Setting name} saved.当对象被删除时使用{Setting name} deleted.仓库中的实际落地案例可以一一对照场景实际文案源码位置开关型开启/关闭Defensive mode enabled./Defensive mode disabled.client/dashboard/sites/settings-defensive-mode/index.tsx普通保存Profile saved.client/dashboard/agency/partner-directory/details/details-content.tsx普通保存带对象名Contact details for %s saved.client/dashboard/domains/domain-contact-details/index.tsx删除DNS record deleted.client/dashboard/domains/domain-dns/actions.tsx删除Domain forwarding rule for %s deleted.client/dashboard/domains/domain-forwarding/delete-modal.tsx从这些案例可以提炼出成功消息的完整句式公式{Setting name} {enabled | disabled | saved | deleted} .其中{Setting name}是用户操作的具体对象名消息以过去式动词收尾并以句号结束呼应 2.2 中Snackbar 消息必须加句号的规则。4.2 例外场景无法即时生效的操作There will be exceptions, such as when the setting cant be changed instantly, but we still want to show success to the user: Change of domain ownership requested.文档明确承认存在例外当设置无法即时生效但 UI 仍要向用户展示已受理的成功反馈时可以用被动词态/请求式文案Change of domain ownership requested.注意这条例外的两个要点原文档特别强调设置名仍然出现在消息中这里即domain ownership消息以过去式动词结尾这里是requested。也就是说即使脱离了enabled/disabled/saved/deleted四个标准动词句式骨架{对象名} 过去式动词 句号依然成立只是动词从即时完成语义换成了已提交请求语义。相应地失败场景也可以简化Failed to change domain ownership.——不必展开成功本应意味着一次请求已被发出这种细节见原文档对最后一个错误消息的说明。4.3 错误消息统一以 Failed 开头错误消息应尽可能提供帮助信息虽然并非总能做到并且必须以 Failed 开头。原文档给出四个标准模板Failed to enable {setting name}. Failed to disable {setting name}. Failed to save {setting name}. Failed to change domain ownership.仓库中有大量对应的实际实现例如client/dashboard/me/language/index.tsxcreateErrorNotice( error.message ?? __( Failed to save language. ) )client/dashboard/me/mcp/index.tsxerror: __( Failed to save settings. )client/dashboard/me/billing-payment-methods/index.tsxcreateErrorNotice( __( Failed to delete payment method. ) )client/dashboard/domains/domain-dns/actions.tsxerror: __( Failed to delete DNS record. )这些错误消息与成功消息一一对应saved↔Failed to savedeleted↔Failed to deleteenabled/disabled↔Failed to enable/disable句式完全对称便于用户理解我做的操作失败了。4.4 Snackbar 消息必须以句号结尾And remember, snackbar messages end with a period.原文档在 Snackbar 一节末尾再次强调句号规则作为收尾提醒。这与 2.2 的表格相互印证Snackbar 是完整句子类别即使是最短的Profile saved.也要带句号。可以看到仓库中所有 snackbar 文案client/dashboard/agency/resources/mcp/use-mcp-settings.ts 的MCP settings saved.等都无一例外地以句号结尾。五、源码落地Snackbar 消息在代码中如何呈现理解规范之后再看这些文案在 Dashboard 中如何被真正渲染成 Snackbar有助于在写文案时建立代码视角。5.1 运行时通知createSuccessNotice / createErrorNoticeDashboard 使用wordpress/notices的 store 来创建通知并通过type: snackbar指定为 Snackbar 形态。以 Defensive mode 设置页 client/dashboard/sites/settings-defensive-mode/index.tsx 为例const handleSubmit ( data: DefensiveModeSettingsUpdate ) { mutation.mutate( data, { onSuccess: () { createSuccessNotice( data.active ? __( Defensive mode enabled. ) : __( Defensive mode disabled. ), { type: snackbar } ); }, onError: () { createErrorNotice( __( Failed to save defensive mode settings. ), { type: snackbar, } ); }, } ); };这段代码几乎就是 4.1 与 4.3 模板的教科书式实现onSuccess里按data.active分支输出Defensive mode enabled./Defensive mode disabled.onError输出Failed to save ...。5.2 例外落地SSH 访问消息SSH 开关client/dashboard/sites/settings-sftp-ssh/ssh-card.tsx展示了文档规则 现实复杂度的平衡createSuccessNotice( __( SSH access has been successfully enabled for this site. ), { type: snackbar, } ); // ... else 分支SSH access has been successfully disabled for this site.它保留了enabled/disabled的过去式动词与句号但为了提供更多上下文哪个站点的 SSH、操作成功把消息扩展为完整句。这说明文档模板是底线基线——在包含设置名 过去式动词 句号的前提下可以根据业务需要适当补充信息。此外这段代码还在显示成功消息前先await queryClient.fetchQuery( sshKeysQuery() )等待 SSH 密钥加载完毕避免 Snackbar 在表单就绪前提前弹出——一个与文案无关但直接影响用户体验的时序细节。5.3 页面加载型 SnackbarFlashMessage 组件除了运行时 mutation 回调里弹出的 SnackbarDashboard 还支持页面加载时弹出 Snackbar通过 URL 查询参数flash传递消息 ID组件挂载后调用createSuccessNotice/createErrorNotice同样指定type: snackbar并清理 URL。实现位于 client/dashboard/components/flash-message/index.tsx。这意味着 snackbar 文案既可能出现在操作完成瞬间也可能出现在一次页面跳转之后——两种场景下文案规范完全一致。六、快速自查清单把原文档浓缩成一张可复用的 checklist供写文案或做 Code Review 时逐项核对拼写是否全部为美式英语customize/color/center句号Snackbar 消息是否以.结尾按钮、表单标签、标题是否没有句号引号用户可见文案是否使用了弯引号“”与弯撇号’而非直引号/大小写按钮、弹窗标题、表单标签、DataViews 字段标签是否为 sentence caseHosting Dashboard 作为产品名时是否保持专有名词大写Snackbar 成功消息是否为{Setting name} enabled./disabled./saved./deleted.模板开关用 enabled/disabled普通保存用 saved删除用 deleted例外场景是否仍包含设置名并以过去式动词结尾如Change of domain ownership requested.Snackbar 错误消息是否以Failed开头Failed to enable/disable/save/delete/change ...遵循这套规范Dashboard 的所有用户可见文案就能保持高度一致的语调与句式用户在开关 SSH、调整 Defensive mode、管理 DNS 记录等场景中获得的反馈始终可预期、可理解——这也正是 typography-and-copy.md 这份文档存在的全部意义。赞分享前端CMS【免费下载链接】wp-calypsoThe JavaScript and API powered WordPress.com项目地址https://gitcode.com/gh_mirrors/wp/wp-calypso点击查看免费下载相关推荐wp-calypso Multi-site Dashboard 开发规范与实践TanStack 技术栈、Mutation Snackbar、国际化与暗色模式的工程指南wp calypso Multi site Dashboard 开发规范与实践TanStack 技术栈、Mutation Snackbar、国际化与暗色模式的前端CMS如何正确使用专有名词大小写中文文案排版终极指南如何正确使用专有名词大小写中文文案排版终极指南 中文文案排版指北是一份致力于统一中文文案和排版相关用法的开源项目旨在降低团队成员之间的沟通成本增强网站气质文档教程终极music21文档编写指南从入门到精通的完整技术规范与实践终极music21文档编写指南从入门到精通的完整技术规范与实践 music21是一款强大的计算音乐学工具包Toolkit for Computational音视频开发工具创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考