Yii 2 官方文档编写风格指南：写作规范、提示块体系与翻译协作实战

后端Web框架【免费下载链接】yii2Yii 2: The Fast, Secure and Professional PHP Framework项目地址https://gitcode.com/gh_mirrors/yi/yii2点击查看免费下载本篇技术指南以 Yii 2 官方仓库中的 documentation_style_guide.md 为核心系统讲解 Yii 官方文档的写作规范从文风、格式、列表与提示块Block标记到代码对象引用、大小写约定、文档校验脚本与译者署名机制。读完本文你将掌握一套可直接套用的 Yii 文档写作与翻译协作流程并能理解 docs/guide 目录下各语言指南为何在结构上高度一致。一、指南的地位与适用范围docs/documentation_style_guide.md是 Yii 2 官方仓库中面向所有文档编写者与翻译者的规范性文件。它规定了编写或编辑任何 Yii 文档时Guidelines to go by when writing or editing any Yii documentation应当遵循的通用准则。文档作者在开头即注明This needs to be expanded.说明这是一份持续演进、鼓励社区补充的活文档。从仓库结构看本指南约束的对象正是 docs/guide英文官方指南及其全部翻译版本如 docs/guide-zh-CN、docs/guide-de、docs/guide-ru 等十余个语言目录。这些指南目录中普遍存在两类由本文档规定产生的配套文件blocktypes.json提示块标记的本地化翻译表translators.json译者署名列表。理解了本指南就等于掌握了阅读与参与 Yii 官方文档工作的通行规则。二、通用文风General Style原文档对写作风格提出了五条核心要求这些要求直接决定了 Yii 官方文档的阅读体验尽量使用主动语态Try to use an active voice。主动语态让句子更直接、动作主体更明确例如Yii 会缓存该查询结果优于该查询结果会被缓存。使用简短、陈述性的句子Use short, declarative sentences。短句降低阅读门槛尤其适合面向国际读者的技术文档。尽可能用代码示例来阐释观点Demonstrate ideas using code as much as possible。Yii 指南的实践是能上代码就上代码例如在讲解组件配置时直接给出配置数组而不是长篇文字描述。绝不使用weNever use we。因为文档背后的主体是 Yii 开发团队或 Yii 核心团队the Yii development team or the Yii core team更推荐的说法是站在框架或指南本身的角度来表述例如Yii 提供……或本指南将介绍……而非我们实现了……。使用牛津逗号Use the Oxford comma。即列举三项及以上时最后两项之间也要加逗号写 this, that, and the other而不是 this, that and the other。这些规则不仅适用于英文原文翻译版本也应尽量在目标语言中保留主动、简洁、以代码说话的精神。三、格式与列表规范Formatting Lists3.1 强调格式强调一律使用斜体italics严禁使用全大写、粗体或下划线来代替强调。在 Yii 指南正文中可以看到大量此规范的实例例如 caching-data.md 中的斜体应用贯穿全文。3.2 列表规则有序数字列表每一项都应是完整的句子并以句号结尾Numeric lists should be complete sentences that end with periods。无序项目符号列表每一项应以分号结尾的短语片段fragment呈现最后一项以句号结尾。这一数字列表用整句、符号列表用片段的约定在文档渲染时能保持视觉与语法的双重一致性也方便翻译者判断每项是否需要补全主语。四、提示块体系Blocks四类标记与本地化机制提示块是 Yii 官方文档中最具辨识度的排版元素也是本风格指南着墨最多的部分。4.1 四类提示块提示块使用 Markdown 引用语法 Type:开头共四种类型语义梯度分明标记用途 Warning:用于安全风险及其他严重问题bad security things and other problems Note:用于强调核心概念、需要规避的事项key concepts, things to avoid Info:一般性信息an aside语气弱于 Note Tip:进阶技巧、补充内容对部分读者有用但不一定人人需要此外冒号之后的句子必须以大写字母开头The sentence after the colon should begin with a capital letter。4.2 实际文档中的用法示例在英文官方指南中四类提示块均有大量真实用例例如 caching-data.md Warning: Cached values are stored with PHPs native serialize() ...——提醒缓存序列化的安全边界 Note: Do not cache a false boolean value directly ...——强调易错点 Info: Some DBMS (e.g. MySQL) ...——补充性信息 Tip: You can register multiple cache application components ...——进阶建议。中文指南 docs/guide-zh-CN/caching-data.md 中的对应条目也保留了这一结构。4.3 翻译提示块blocktypes.json原文档明确规定翻译文档时Warning、Note、Info、Tip这些 Block 指示词本身不应被翻译应保持原样只翻译冒号之后的内容。如果需要翻译Type这个词则必须在每个语言指南目录下创建blocktypes.json文件存放对应翻译。原文档给出的德语示例{ Warning:: Achtung:, Note:: Hinweis:, Info:: Info:, Tip:: Tipp: }仓库中的 docs/guide-de/blocktypes.json 与示例完全一致而 docs/guide-zh-CN/blocktypes.json 则提供了中文映射{ Warning:: 警告, Note:: 注意, Info:: 信息, Tip:: 提示 }从源码结构看该文件的价值在于文档渲染工具可以根据目标语言读取blocktypes.json自动将 Warning:等标记渲染为本地化文案而.md源文件中的标记保持英文从而保证多语言版本在结构上完全对齐、便于后续 diff 与同步。因此为新增语言创建blocktypes.json是该语言文档可用的前提条件之一。五、引用与命名规范References5.1 版本与章节称谓只能写Yii 2.0或Yii 2不能写 Yii2 或 Yii2.0指南的每一页称为一个sectionEach page of the guide is referred to as a section。5.2 代码对象的引用语法引用代码对象时有一套严格的写法目的是与 API 文档自动生成链接类使用完整命名空间如yii\base\Model类属性即使属性并非静态也使用静态语法如yii\base\Model::$validators类方法同样使用静态语法并带括号以明确其为方法如yii\base\Model::validate()。5.3[[]]API 链接标记所有代码对象引用都应写在[[]]中以生成指向 API 文档的链接例如[[yii\base\Model]][[yii\base\Model::$validators]][[yii\base\Model::validate()]]从英文指南正文可以印证这一约定的实际效果比如 concept-components.md 中的 Components are instances of[[yii\base\Component]]、caching-data.md 中的[[yii\caching\Cache::getOrSet()|getOrSet()]]写法——竖线右侧是显示文本左侧是完整引用最终会渲染为 API 文档链接。中文指南同样保留了[[yii\caching\Cache::get()|get()]]形式的引用。六、大小写约定Capitalizations写作Web而不是 web写作the guide / this guide而不是 the Guide。这一约定避免了英文中Guide被误当作专有名词大写保持了术语的一致性。七、文档校验用 grep 检查损坏链接原文档提供了一组校验脚本用于发现指南中的链接问题。需要说明的是这些命令是针对 Yii 官方文档的编写/审核流程使用前请确认运行环境满足 grepPCRE 模式支持grep -rniP \[\[[^\],]?\][^\]] docs/guide* grep -rniP [^\[]\[[^\]\[,]?\]\] docs/guide*逐条解读第一条用于查找格式错误的[[...]]代码引用例如[[yii\base\Model]少了右方括号或[[...]]后紧跟非法字符。正则\[\[[^\],]?\][^\]]匹配以[[开头、内容不含]、、、随后是单个]但后面不是]的模式即不完整的引用写法。第二条用于查找孤立成对的]]例如多余的右方括号[...]]]或不匹配的闭合正则[^\[]\[[^\]\[,]?\]\]匹配前面不是[、以单个[开头、内容不含方括号与逗号、以]]结尾的模式。两个命令的-r递归、-n显示行号、-i忽略大小写、-PPCRE 正则参数组合可在docs/guide*覆盖英文指南及全部语言翻译目录下快速定位疑似破损的[[]]引用。原文档同时提示可能出现少量误报some false-positives may occur审核时需人工复核命中行。这一节的存在说明Yii 官方对文档的可链接性有自动化兜底编写新文档或翻译后建议运行上述命令自查一遍。八、译者署名机制Attribution of Translators翻译者的姓名会出现在渲染版指南的作者列表中为此每个非英语语言指南目录下都应创建translators.json文件内容为参与翻译人员的姓名数组如果你为翻译做出了重要贡献欢迎发送 Pull Request 添加自己的名字。原文档给出的示例[ Jane Doe, John Doe ]仓库中的实际案例是 docs/guide-de/translators.json包含Carsten Brandt一人。从仓库各语言目录如 docs/guide-zh-CN、docs/guide-ja、docs/guide-ru 等均存在translators.json与blocktypes.json来看这两份文件已是 Yii 官方文档多语言协作的标准基础设施前者落实署名激励后者保障提示块在渲染层的本地化。九、总结与落地清单围绕 docs/documentation_style_guide.mdYii 2 的文档工作形成了清晰可复用的规范闭环写作层主动语态、短句、代码优先、禁用we、牛津逗号强调只用斜体数字列表用完整句、符号列表用分号片段。结构层四种提示块Warning / Note / Info / Tip承担不同强度的信息传达翻译时标记保留原文、内容本地化映射关系写入blocktypes.json。引用层代码对象一律使用完整命名空间的静态语法并用[[]]包裹以生成 API 链接版本写法统一为 Yii 2.0 / Yii 2。质量层用两条 grep 校验命令扫描docs/guide*下的[[]]链接破损注意甄别误报。协作层翻译文档通过translators.json登记署名鼓励社区贡献者以 Pull Request 方式参与。这套规范既是 Yii 官方文档docs/guide能保持多语言结构一致、术语统一的原因也为其他开源项目的文档治理提供了一个可直接借鉴的范例。赞分享后端Web框架【免费下载链接】yii2Yii 2: The Fast, Secure and Professional PHP Framework项目地址https://gitcode.com/gh_mirrors/yi/yii2点击查看免费下载相关推荐Fleet 写作规范与文档协作指南从文章元数据到 Markdown 写作风格Fleet 写作规范与文档协作指南从文章元数据到 Markdown 写作风格 Fleet 是一个开源的设备管理device management平台其仓后端前端企业应用运维网络安全Remotion 官方文档写作指南MDX 页面结构、写作规范与文档专用组件体系Remotion 官方文档写作指南MDX 页面结构、写作规范与文档专用组件体系 本文是 Remotion 项目面向文档贡献者与维护者的「写文档」技术规范。它围音视频AI 应用前端Home Assistant YAML 风格指南官方文档示例的编写规范与模板实践Home Assistant YAML 风格指南官方文档示例的编写规范与模板实践 本篇指南系统讲解 Home Assistant 官方文档中 YAML 示例文档教程智能家居物联网上一篇decimal.js源码解读从Decimal类设计看高精度算法实现下一篇elasticsearch-head命令行参数详解自定义启动选项与配置创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考