以 Astro 7.4.1 和 Starlight 0.42.6 构建的 Zig 0.17.0 与 0.17.1 固定版本文档站。收录官方语言参考和官方标准库文档资产覆盖的全部模块,提供简体中文与英文阅读、接口索引、全文搜索、源码行定位、语言与版本切换。
- 网站:https://izrino.github.io/zig-docs/
- 官方原文:https://ziglang.org/documentation/0.17.0/、https://ziglang.org/documentation/0.17.1/
- 默认语言:简体中文。0.17.0 保留
/zh-cn/、/en/;0.17.1 使用/zh-cn/0.17.1/、/en/0.17.1/。
“入门”在全部版本的中英文概览与侧栏中可见,各版本共用同一组内容,不随版本切换更新。英文采用官方英文原文,现有中文章节保留原有译文;新增“语法规则”保留完整 PEG 规则,仅翻译自然语言注释。
原文存放在 upstream/intro/{en,zh-CN}/ 和 upstream/intro/grammar/;语法原文固定到来源提交并记录大小与 SHA-256,译文维护在 translations/intro/grammar.zh-cn.json。语法文件来自 ziglang/zig-spec 的 master 分支,不标作特定 Zig 发行版本的规范。
npm run extract:intro该命令离线生成 content/{en,zh-cn}/intro/,内容校验会核对原文快照、译文覆盖与生成后的完整语法文本。
需要 Node.js 24。日常构建直接读取仓库中的快照与译文,不联网抓取,也不调用翻译服务。
npm ci
npm run dev访问 http://localhost:4321/zig-docs/。开发服务器不提供正式全文索引;搜索需要构建后通过预览服务器验证。
npm test
npm run lint
npm run check
npm run build
npm run validate:links
npx playwright install chromium
npm run test:e2ebuild 先执行完整内容校验,再构建静态站点与 Pagefind 索引。译文缺失、代码标记变更、快照校验和不匹配或页面集合不完整都会阻断构建。
-
upstream/{0.17.0,0.17.1}/:各版本的官方语言参考、标准库页面、JavaScript、WebAssembly、源码归档和许可证。 -
upstream/{0.17.0,0.17.1}/manifest.json:版本、来源、抓取时间、资源大小与 SHA-256。 -
translations/:0.17.0 逐段译文及原文哈希;translations/0.17.1/只保存 0.17.1 新增或变更的译文、原文哈希及原样保留项。标准库按注释内容去重。 -
content/{en,zh-cn}/:0.17.0 的页面;content/0.17.1/{en,zh-cn}/:0.17.1 的页面与独立清单。 -
reports/:0.17.0 的覆盖率、声明和链接记录;reports/0.17.1/保存新版本对应记录与差异摘要。 -
scripts/:快照、官方解析器适配、翻译校验和内容生成。 -
tools/tokenizer.wasm:使用 Zig 0.17.0 官方词法分析器编译的独立校验模块。0.17.0 语言参考按 53 个顶层章节组织,保留 352 个标题;标准库按 538 个源码模块组织,保留 37,803 个声明记录,包括私有声明、条件类型成员、类型函数及别名。官方解析器会为不同局部容器生成相同完整名称;同一页面中遇到这种情况时,后续声明以源码行号补充锚点,避免覆盖记录。
中文翻译保留标识符、字面量、命令及编译器输出,仅翻译自然语言与代码注释。代码通过官方词法分析器比较非注释标记;注释行数不足时补空注释,以保持原始行号。原文的语义和限制条件优先于措辞润色;上游没有提供说明的接口不补造说明。
verbatim-*.json 记录经审阅后原样保留的代码、公式、路径和技术专名。包含拉丁字母而不含汉字的单元必须登记明确理由,单词说明也受此门禁约束。protected-exceptions-*.json 仅允许指定原文与译文哈希之间的精确修正,用于处理上游未闭合反引号、ASCII 图示中的自然语言标签等情况。带 renderedTextBlocks 标记的图示还必须与同一源码模块的原文、译文围栏逐字匹配;它们不会关闭实际源码的词法标记校验。
所有站外回退引用都会通过官方解析器再次查找;官方能够解析、但站内没有收录的目标会阻断生成。真正无法解析的上游引用保存在 reports/upstream-links.json。reports/semantic-review.json 记录额外的敏感语义抽样、英文残留扫描及修正依据;抽样结果不等同于对全部译文的正确性证明。
大型标准库模块使用可筛选、分页和键盘操作的接口索引,全部正文与接口锚点仍保留在当前页面。reports/verification.json 保存首次发布前的本地验收统计与性能测量;本地性能数据不代表线上网络延迟。reports/deployment.json 记录首次部署的提交、通过全部门禁的工作流和实际线上验收结果。
正文使用自托管的 Source Sans 3 与 Noto Sans SC(思源黑体),代码使用 JetBrains Mono,中文注释回退至 Noto Sans SC。三种字体均采用 SIL Open Font License 1.1;随站分发的许可证见 public/licenses/fonts-OFL.txt。字体通过 Fontsource 的 Unicode 范围分片按需加载,使用 font-display: swap,并通过 src/components/Head.astro 预加载常用的拉丁字型分片,避免字体切换造成正文重排;不请求外部字体服务。
语言参考的完整示例与命令输出使用 Starlight 已包含的 Expressive Code,在生成内容时执行 Shiki 高亮。标准库的短签名与完整源码保留上游高亮、行号与源码锚点,避免大型模块重复渲染。代码行号在横向滚动时固定在左侧;超过 96 行的示例限制高度并可纵向滚动。标准库源码框的复制按钮位于折叠标题栏,复制结果仍不包含行号。scripts/lib/code-frame.mjs 保留原始空白、选择示例语言,并断言渲染后文本逐字一致;运行 npm run extract 同时重生成并格式化 src/styles/expressive-code.css。日常构建直接使用已提交的 HTML 与样式。
界面验收包括 390、768、1004、1440 像素下的双语排版、字体实际加载、明暗主题、逐字复制、布局偏移和字体载荷;对应测试位于 tests/e2e/reading.spec.ts。完整内容校验还会把语言参考中的英文代码逐块与官方快照比较。
本次排版调整的设计依据与代码展示库取舍见 docs/reading-experience-brief.md,本地验收结果见 reports/reading-experience.json。复制测试分别核对传给剪贴板的原始字符串和系统剪贴板读回值,仅对 Windows 读回值的 CRLF 换行做等价处理。
此仓库维护 0.17.0 与 0.17.1,不跟随开发版本自动更新。0.17.0 继续使用原命令;0.17.1 单独执行:
npm run snapshot -- 0.17.1
npm run extract -- 0.17.1无版本参数时,上述命令仍指向 0.17.0。快照脚本复用已有固定资源;若需重新抓取,应先将旧快照移到工作区外备份,再运行脚本。脚本还会下载并校验官方源码压缩包以提取许可证,临时压缩包保存在 .cache/。Linux/macOS 需要支持 xz 的 tar;Windows 的 tar 不支持 xz 时使用 Python 3 标准库回退。
原文发生变化时,需要审核来源及校验和、重新建立翻译清单、补齐译文,再生成内容。必须审查内存所有权、分配释放、并发、未定义行为、错误传播和数值边界等语义,并运行全部校验。禁止用英文原文代替缺失中文通过构建。
对于评审过程中发现的疑似上游笔误,参见 reports/upstream-notes.json。页面翻译忠实保留了固定版本原文,这些记录不是对上游行为的更正。
修改词法分析器包装时,需要同版本 Zig 编译器,具体编译命令见 scripts/tokenizer.zig。重新编译后同时更新校验和并运行词法分析测试;一般构建无需安装 Zig。
GitHub Pages 使用 Actions 部署。推送 main 或手工触发工作流后,先测试、检查格式和类型、校验内容、构建、检查站内链接与浏览器交互,再上传并部署静态产物。校验失败不会替换已部署站点。
站点固定部署于仓库子路径 /zig-docs/。修改仓库名称或部署域名时,需要同时更新 Astro 配置、生成器中的站内链接、测试与工作流。
本站为非官方中文文档。Zig 原文、源码与随附第三方许可归原作者所有;上游许可证保存在 upstream/{0.17.0,0.17.1}/LICENSE(两版 SHA-256 相同),网站提供可直接访问的副本。源码中的第三方许可头和版权声明一并保留。站点实现与译文采用根目录的 MIT 许可证。