文档教程【免费下载链接】TypeScriptTypeScript 使用手册中文版翻译。http://www.typescriptlang.org项目地址https://gitcode.com/gh_mirrors/typ/TypeScript点击查看免费下载本指南面向希望参与 TypeScript 官方手册中文翻译的开源贡献者围绕仓库根目录下的 CONTRIBUTING.md 展开完整讲解挑选待翻译条目 → Fork 并本地翻译 → Markdown 风格检查 → 提交 Pull Request的全流程并深入剖析仓库内置的 lint 检查工具 lint.js 与文档组织结构book.toml、SUMMARY.md让你能够以规范、可合并的方式为这本《TypeScript 使用指南手册》中文版贡献译文。一、先认识这个仓库贡献的目标是什么本仓库gh_mirrors/typ/TypeScript是TypeScript 使用手册中文版即对 TypeScript 官方及开源社区书写的编程手册、版本发布说明等综合内容的中文翻译工程其定位在 PREFACE.md 中有明确交代项目自 2015 年创建以来长期维护持续跟进 TypeScript 各版本的 Release Notes并沉淀了手册zh/handbook、进阶手册zh/reference、声明文件指南zh/declaration-files、工程配置zh/project-config等多套中文文档。贡献者提交的每一份译文最终都会汇入这套以 mdBook 方式组织的中文手册中。仓库根目录的 book.toml 定义了图书元信息与构建行为[book] authors [钟胜平, zhongsp] language zh-Hans multilingual false src ./ title TypeScript 使用指南手册 description TypeScript Handbook 中文翻译。 [build] build-dir docs # the directory where the output is placed create-missing true # whether or not to create missing pages use-default-preprocessors true # use the default preprocessors也就是说所有中文 Markdown 文档以仓库根目录src ./为源通过 mdBook 构建输出到docs目录仓库中docs/下的index.html、book.js、searchindex.js等即为构建产物而页面之间的导航层级则由 SUMMARY.md 统一编排。理解这一点有助于你在提交译文时判断新文档应该放在哪个目录、是否需要在 SUMMARY.md 中登记。二、贡献流程总览CONTRIBUTING.md 将整个贡献流程浓缩为三个步骤这也是你从围观者变为贡献者的标准路径从队列中选择一项待翻译的条目优先挑选仓库中标记为help wanted的未翻译/待翻译条目避免与他人重复劳动。Fork 仓库添加译文最后检查 Markdown 风格在本地完成翻译后运行仓库自带的 lint 检查确保文档风格合格。提交 Pull Request将译文通过 Pull Request 合入主干。下面逐一展开。三、第一步如何挑选一项待翻译的条目挑选待翻译条目是贡献流程的起点。在贡献之前建议先通读一遍 README.md 的目录部分与 SUMMARY.md掌握手册现有的文档覆盖范围判断哪些章节仍是缺口。从当前仓库的目录结构看可以找到若干已列入规划但尚未完成翻译的条目这类条目正是合适的贡献目标。例如SUMMARY.md 第 80 行登记了「与其它构建工具整合」一页对应的目标路径为zh/project-config/integrating-with-build-tools.md但该文件在当前仓库的zh/project-config/目录中并不存在zh/handbook-v2/目录下目前仅有type-manipulation/下的少量文件如 template-literal-types.md新版 Handbook 的更多章节仍待翻译。这类SUMMARY 中已规划、磁盘上缺失的文档即为典型的待翻译条目。此外翻译节奏上也可以参考 PREFACE.md 的说明项目会持续跟进 TypeScript 新版本的 Release Notes参见 zh/release-notes 中从 1.1 到 6.0 的完整序列因此每当 TypeScript 发布新版本时对应版本的发布说明翻译往往就是最新的待办事项。提示在动手翻译某一篇之前务必先在仓库内搜索确认该主题是否已被其他贡献者翻译或正在翻译避免重复提交同一条目。四、第二步Fork 仓库并准备本地翻译环境选定条目后Fork 仓库到自己的命名空间并克隆到本地随后安装依赖。仓库的依赖与脚本声明在 package.json 中{ name: typescript-handbook-cn, scripts: { test: node ./lint.js, lint: node ./lint.js }, license: MIT, devDependencies: { glob: 7.1.3, markdownlint: 0.11.0 }, packageManager: yarn4.1.0 }可以看到项目通过npm管理脚本、依赖glob与markdownlint两个开发依赖并声明了包管理器为yarn4.1.0。按 CONTRIBUTING.md 的指引在仓库根目录执行npm install npm run lintnpm install会依据package.json安装glob与markdownlint安装后通常会在node_modules中出现这两个包npm run lint实际等价于npm test二者都执行node ./lint.js对仓库内全部 Markdown 文件做风格检查。执行完毕后在你选定的zh/目录下新建对应的中文 Markdown 文档如zh/project-config/下补齐某篇缺失文档或在现有章节中修订译文并按照下文第五节的规范自查 Markdown 风格。五、第三步理解并运行 Markdown 风格检查lintlint.js 是仓库自带的文档风格检查器它直接决定了你的译文能否通过检查。其核心机制是用glob收集仓库内全部**/*.md文件排除node_modules/**/*即所有中文 Markdown 文档都要接受检查调用markdownlint按 lint.js 中内联的规则配置逐条校验额外自定义一个围栏代码块缩进检查函数统计错误数量后以进程退出码反馈结果——只要有任一文件报错lint.js就会以非零退出码退出即npm run lint失败。5.1 lint 规则解读lint.js 中逐条配置了 markdownlint 规则每条对应 Markdown 风格的一个方面翻译者最需要遵守的硬性规则包括MD003标题使用 ATX 风格#前缀且MD018/MD019#后必须紧跟一个空格、不允许多余空格MD022/MD023标题前后必须留空行且必须从行首开始MD007无序列表缩进为 2 个空格MD005/MD006 要求同级列表项缩进一致、列表从行首开始MD009不允许行尾多余空白MD010不允许硬 Tab 缩进MD011链接语法不能写反MD012不允许连续多个空行MD029有序列表序号采用 1./顺序 风格MD030列表标记后要有空格MD031/MD032围栏代码块前后必须有空行列表周围必须有空行MD034不允许裸 URL必须用链接语法包裹MD035分隔线统一使用---MD037强调符号*、_内侧不能有多余空格MD039链接文本内不能有多余空格MD040围栏代码块必须声明语言。同时lint.js 也关闭了若干规则翻译时无需为此纠结MD013行长不限、MD014命令前允许$提示符、MD024允许标题重复、MD025允许多个一级标题、MD033允许内联 HTML、MD036允许用强调代替标题、MD038允许代码跨度内空格、MD041文件首行不强制是一级标题等。5.2 自定义检查围栏代码块缩进lint.js 末尾的checkForImproperlyIndentedFencedCodeBlocks函数实现了一条额外规则紧跟列表项之后的围栏代码块 开头行必须缩进到列表项第一个非空白字符的列位置否则视为错误并输出提示例如A fenced code block following a list item must be indented to the first non-whitespace character of the list item.判断逻辑是对每个以^(\s*)\S匹配到的代码块起始行取其缩进长度再通过getCorrectStartingColumnForLine向上回溯最近的非空行若最近一行是列表项匹配^\s*([\*\-]|(\d\.))\s*则以该列表项文本起点作为正确的缩进列。这意味着在列表项下方写示例代码时代码块必须与列表项正文对齐而不是与列表标记*、-、1.对齐。这是翻译含步骤列表和示例代码的文档时最常见的坑之一。5.3 lint 与文档内容的关系值得注意的是lint 检查的是Markdown 风格而非译文内容正确性——它不校验翻译是否通顺、术语是否统一。因此通过 lint 只代表格式合格内容的准确性仍需你自行把关。可以参考仓库既有中文译文的写作风格如 zh/project-config/tsconfig.json.md、zh/handbook/basic-types.md保持术语翻译与全书一致。六、第四步提交 Pull Request译文完成并通过npm run lint后即可提交 Pull Request。结合仓库的工程组织方式一个高质量的 PR 通常包含译文文件新增或修改zh/下的对应 Markdown 文档导航登记如需新增页面在 SUMMARY.md 或 README.md 的目录中补充对应条目使新译文进入手册导航风格合规npm run lint在本地零报错。提交 PR 时建议在描述中说明所翻译的条目主题便于维护者快速定位审核范围。仓库采用 MIT 协议见 package.json 与根目录 LICENSE提交译文即表示你同意以该协议授权你的贡献。七、常见问题与注意事项依赖安装失败项目声明packageManager: yarn4.1.0若你的环境使用旧版 npm可能遇到锁文件仓库根目录有 yarn.lock版本不匹配的问题可按package.json声明切换对应包管理器后重试。lint 大量报错不知从何下手npm run lint输出中每一条都会标明文件名 行号 违反的规则按 MD 规则号对照上文 5.1 节逐条修正即可。列表后的代码块缩进报错优先对照 5.2 节的缩进规则将代码块起始列的缩进调整到与列表项正文对齐。不确定翻译对象是否已存在翻译前先在本仓库内用关键词搜索对应英文主题的中文文档例如在zh/目录下搜索相关术语确认无现成译文后再动手。仓库为只读镜像本仓库仅用于查看、安装、运行与配置贡献操作请在你的 Fork 与上游仓库之间完成不要在镜像仓库内直接修改文件。结语从挑选待翻译条目到 Fork 本地翻译、通过 lint.js 的 Markdown 风格检查再到提交 Pull RequestCONTRIBUTING.md 给出了简洁清晰的贡献路径。配合仓库中 package.json、lint.js、SUMMARY.md 与 book.toml 等工程文件的佐证你完全可以对照本指南独立完成一次合规的中文翻译贡献让《TypeScript 使用指南手册》中文版在大家的协作下持续完善。赞分享文档教程【免费下载链接】TypeScriptTypeScript 使用手册中文版翻译。http://www.typescriptlang.org项目地址https://gitcode.com/gh_mirrors/typ/TypeScript点击查看免费下载相关推荐SciPy 贡献指南从 Pull Request 规范到完整提交流程SciPy 贡献指南从 Pull Request 规范到完整提交流程 导读 本文以 SciPy 仓库根目录的 CONTRIBUTING.rst https:/科学计算数据科学高性能计算MiroFish 部署教程3 条路线任选最快 10 分钟本地跑通预测引擎MiroFish 部署教程3 条路线任选最快 10 分钟本地跑通预测引擎 MiroFish 是一款简洁通用的群体智能预测引擎你上传一份报告、新闻稿甚至小说人工智能大模型AI Agent多智能体Agent 编排Bug报告Bug报告 描述问题 简要清晰地描述遇到的bug 复现步骤 1. 执行命令 ... 2. 操作 .... 3. 观察到错误 .... 预期行为 应该人工智能计算机视觉深度学习上一篇Pathway连接器生态打通数据源与目的地的完整指南下一篇3个API端点配置陷阱让UI-TARS部署失败一文搞定参数设置与验证创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考