简介MLIR官方文档中文翻译项目是一份面向编译器开发者与研究者的完整学习资料适合有一定编译器基础、希望掌握MLIR多级中间表示的中高级开发者全面翻译官方文档与教程系统讲解方言、操作、属性、类型转换、Pass管理器及代码生成等核心机制。资源包共316个文件以89个Markdown译稿为主干辅以41个C头文件、40个C源文件、36个MLIR示例、23个txt说明、15个TableGen定义以及13个SVG示意图等整体仅1.05MB轻量却覆盖完整知识体系。目前已有155人学习。除翻译文本外资源还包含Toy语言示例及多种源码与模式定义文件便于读者对照理解方言注册、IR生成与转换流程从多级中间表示基础设施到具体代码生成技巧均配有详解既能用于自学入门也可作为研发MLIR相关编译器功能时的参考手册。1. MLIR官方文档中文翻译项目它在解决谁的哪一类痛点我见过不少编译器和AI框架工程师打开MLIR官方文档后十分钟内就被“方言Dialect”“操作Operation”“Pass管理器”这些词淹没。MLIR官方文档中文翻译项目要解决的正是这条学习链路上的断点把MLIR官方文档与教程资源逐篇翻译按核心概念、多级中间表示基础设施、方言、操作、属性、类型、转换模式、Pass管理器到代码生成的主线组织成完整的中文学习资料。它适合三类人被英文文档劝退的零基础学习者想快速判断MLIR值不值得引入的框架开发者需要给团队铺内部培训资料的技术负责人。这篇笔记不替你读文档但会给你一套拿到这类翻译资源后怎么组织、怎么读、怎么避坑的方法。2. 读懂MLIR官方文档的骨干多级中间表示、方言与Pass管理器不把概念骨架搭起来就去翻译翻出来的中文大概率没人看得懂这也是许多文档翻译项目翻车的共同原因。MLIR官方文档有一个明显特征它是给“已经知道要做什么”的工程师看的规范不是给新手铺的台阶。每个术语背后都压着一层设计意图。只有先把主干立住再逐句翻译术语才立得住读者才跟得上。2.1 从多级中间表示说起“多级”到底指什么传统编译器里大家熟知的中间表示是单层的。LLVM IR在优化阶段基本保持同一抽象层级C/C前端降下来是什么级别优化就基于什么级别做。MLIR则把“中间表示”本身做成可以组合、可以升降的体系。一个编译流程里可以同时存在多个抽象层级的IR上层做张量运算中层做循环变换下层做寄存器分配每一层都有自己的表示层与层之间通过转换与降级连接。这就是标题里“多级中间表示基础设施”的基本含义。翻译这一段时第一道坎是Lowering这个词的译法。官方文档里progressive lowering反复出现我见过“渐进式降级”“分层下降”“逐步下移”三种译法出现在同一份资料里。我统一用“渐进式降级”第一次出现时标注英文。原因很简单这个词描述的是IR一层层换血的过程不是一次性翻译成目标代码。如果随手译成“降低”读者会误以为是在讲优化级别。这里值得专门说一句MLIR的“代码生成”不是传统意义上“源码翻译成目标代码”的代码生成。很多读者是从C代码生成、PLC代码生成这类业务背景找过来的第一反应是找一个“生成汇编”的开关。但MLIR里的CodeGen是一整套IR逐级变化的过程最终才落到目标后端。翻译官方文档时要把“代码生成”挂到“多级IR的末端”去理解整篇文档的叙事逻辑才会通顺。2.2 方言与操作官方文档里最劝退的两个基础概念Dialect是MLIR组织一切功能的命名空间。官方定义里方言是一组操作、属性和类型的集合。为什么会叫“方言”因为不同领域的人说不同的行话机器学习框架的人说卷积加速器的人说脉动阵列CPU后端的人说寄存器。MLIR允许所有这些行话在同一个IR体系里共存每套行话就是一种方言。文档中出现频率最高的IR片段长这样// 官方教程里反复出现的例子 func.func main() { %cst arith.constant dense[1.0, 2.0] : tensor2xf64 return }这里用了func和arith两个方言。func是函数层方言arith是算术运算方言。%cst是变量名由constant操作产生dense[1.0, 2.0]是属性描述编译期常量tensor2xf64是类型描述数据形状。func.func、arith.constant这种“方言名.操作名”的写法是翻译文档时必须原样保留的部分。翻译这段代码时能动的只有注释。而且注释不能照字面直译成“这是主函数”要译成“主函数入口”。MLIR的func.func并不等价于C语言的main函数它只是一个函数操作。这类细微差别恰恰是文档翻译中最容易埋雷的地方。Operation操作是IR的基本单元文档里经常直接用缩写Op翻译时建议写成“操作Op”后面再单用“操作”即可。2.3 属性、类型、转换模式与Pass管理器翻译时最绕的四组词这四组词需要先明确定义再谈翻译。类型描述的是数据形状比如tensor2xf64属性描述的是编译期就知道的常量信息比如dense[1.0, 2.0]。两者在官方文档里几乎总是成对出现翻译时要注意上下文不能把“attribute”统一译成“属性”就完事在place attribute on operation这类句子里要能看出“给操作挂属性”的动作。Pattern Rewriting在标题里对应“转换模式”。同一概念在一些资料里也叫“模式重写”我建议以标题用的“转换模式”为准但第一次出现时标注英文。MLIR的优化不是写一个大Pass干完所有事而是注册大量小pattern每个pattern只管一类局部变换Canonicalizer就是由无数小pattern驱动的一个Pass流水线实例。Pass这个词我明确建议保留英文不译。译成“趟”“遍”“通行证”都会造成理解障碍。Pass Manager统一译“Pass管理器”。官方文档里还有一个高频组合Pass Pipeline译成“Pass流水线”或“Pass管线”都可以但全篇只能选一个。这里可以做一个速查表方便动笔前建立对应关系传统编译器里的概念MLIR里的对应物翻译注意点优化模式重写Pattern Rewriting不要泛化成“优化流程”指令选择转换Conversion保留“转换”别写成“指令选择”代码生成后端Target 方言结合上下文判断是否指“代码生成”编译选项Pass 流水线选项保留“Pass”字样基本块跳转图控制流图别缩写成“流程图”我见过有翻译把control flow graph直接写成“控制流程图”读者以为是某种业务流程图实际它特指基本块之间的跳转关系。这类词在动笔前不确认后面很难回头改。我的习惯是在2.1到2.3这些核心概念上花两天时间通读英文原文动手翻第一批文档前先把术语表建好而不是边翻边定译名。3. 组织一次MLIR文档翻译范围、流程与版本对齐怎么做翻译MLIR文档和翻译普通开源项目文档不是一回事。它本质上是一个基础设施翻译工程面对的不是二十篇短文而是几十万字、持续变动的规范。没有流程就开工最后一定会烂尾。这一章讲的是怎么把“这个翻译项目值得做”变成“做得完、能用、敢发布”。3.1 先圈定翻译范围官方教程、核心概念还是全部文档常见做法是把范围分成三批来推进。第一批是Getting Started加官方教程教程会带你写一个自定义方言把操作、类型、转换、Pass管理器全部跑一遍这是普通读者最先碰到的入口。第二批是Rationale、LangRef和Pass Infrastructure这些是概念主干的来源也就是标题里“核心概念”和“多级中间表示基础设施”主要覆盖的部分。第三批才是各方言文档和代码生成相关文档比如循环方言、张量方言、GPU方言、LLVM方言这类。判断标准只有一个按“读者从零开始能不能走通”决定先后。第一批的目标是让读者体验“MLIR原来是这么用的”第二批让读者理解“这些设计为什么存在”第三批按需补。我见过不止一个翻译项目一上来就按官网导航顺序从头翻到尾结果翻了两个月还停在概念目录里读者根本没法上手。那是把英文站复制成中文站不是在做学习资料。3.2 术语表先行地基不打后面全是裂缝动手翻第一个文件之前先建一个术语表文件。把标题里出现的技术名词和官方文档里反复出现的词先列一轮。下面这个表可以直接抄走当模板英文建议译名备注状态Dialect方言首次出现标注英文已确认Operation操作缩写Op保留已确认Pass不译编译术语译了反而难懂已确认Pattern Rewriting转换模式不采用“模式重写”已确认Attribute属性注意与Type区分已确认Type类型描述数据形状已确认Lowering降级统一用“渐进式降级”已确认Conversion转换指方言间的转换已确认Canonicalization规范化不要译成“标准化”已确认Bufferization缓冲化指内存缓冲阶段已确认Code Generation代码生成指IR逐级下降后的产物已确认术语表确认后所有篇章共用一份不允许个人单独发挥。翻译过程中发现更好的译名正确的做法是先更新术语表再做一次全局替换而不是只改眼前这篇。全局替换看起来麻烦实际上比“留着以后一起改”省力得多。3.3 翻译流程与分工机器初翻人工校对的四道关卡个人翻译和团队翻译的流程不一样。一个人做的话我的顺序是先用机器翻译产出初稿再通读初稿改成中文表达然后打开英文原版逐段对照最后把文中所有示例命令在本地跑一遍。团队做的话按“初翻、术语自查、交叉校对、技术校对、合并”五步走。技术校对的人选很关键建议找写过MLIR代码的人而不是英语最好的人。术语可以靠表查语义只能靠懂行的人判断。这一步没法外包给纯翻译。我见过一个项目四道校对全做完但技术校对环节没人真跑过mlir-opt结果文档里一半命令行参数是过时的发布后立刻被读者抓包。3.4 版本对齐用commit把“官方文档天天变”钉住MLIR文档不是独立站点它和LLVM项目源码在同一个仓库里发布。今天翻完的LangRef下个月可能就被上游改动。不对齐版本读者照着文档操作发现源码对不上信任感会立刻归零。做法是四步。第一在翻译项目里记录上游commit哈希。第二每个翻译文件头部标注“基于commit xxxx翻译”。第三定期用git log对比上游文档变动。第四发布资源包时把版本信息写进README。记录上游版本可以用这条命令# 在翻译项目里记录上游版本 git log -1 --format%H -- docs/LangRef.rst命令从仓库里找出最后一次修改LangRef文档的commit哈希把输出结果写进翻译项目的版本说明文件。这样读者一旦发现文档和源码对不上能立刻知道是上游更新了还是翻译本身出错。参数说明--format%H表示只输出完整哈希--后面跟文件路径表示只看该文件的提交记录。没有人愿意用一份不知道对应什么版本的文档这是文档翻译项目最容易忽略却最影响口碑的一环。4. MLIR文档术语对照表十六个关键词的译名与取舍逻辑术语表是一份文档翻译项目的黑匣子读者看不到但每句话的背后都有它。这一章把MLIR官方文档里最高频的十六组词列出来给出推荐译名和取舍理由可以直接拿去做团队评审的讨论底稿。4.1 推荐译名表先统一再开翻英文术语推荐译名取舍说明MLIRMLIR整体保留不译成“多级中间表示语言”Multi-Level多级指抽象层级的数量Intermediate Representation中间表示不缩写为“IR”单用Infrastructure基础设施标题用语保留Dialect方言首次出现标注英文Operation操作文档中Op缩写保留Attribute属性与类型并列出现Type类型不要译成“种类”Pass不译译成“趟”或“遍”都奇怪Pass ManagerPass管理器固定搭配Pattern Rewriting转换模式备选“模式重写”但全篇统一Lowering降级固定搭配“渐进式降级”Conversion转换方言与方言之间的变换Canonicalization规范化不要写成“标准化”Bufferization缓冲化指定进内存缓冲阶段Code Generation代码生成注意是IR级生成这张表的逻辑不是“每个词都要找一个中文对应”而是“哪些词翻译了反而增加理解成本”。Pass和MLIR属于后者保留英文的收益远大于翻译。4.2 哪些词必须保留英文Pass、Dialect、Op的取舍Pass是我第一个坚持不译的词。中文编译资料里它常被译成“趟”“遍”“通行证”读者看到“一遍遍跑”完全无法建立专业对应。不如直接写Pass让读者在中文语境里记住这个英文单词。Dialect的译名“方言”本身是意译不是音译第一次出现写成“方言Dialect”后面单用“方言”即可。Op这个缩写也建议保留。官方文档里“Op”的出现频率远高于“Operation”翻译成“操作”没问题但遇到“Op traits”“Op interface”这类复合结构时建议译成“操作特征”“操作接口”第一次出现标注“操作Op”。不一致的写法会出现在同一句话里“这个Op的操作数”这种表达就是没核对术语表的典型症状。MLIR本身更不需要翻译。有些资料会写成“多级中间表示语言”看起来是把全称翻译了一遍但MLIR并不是一种传统意义上的“语言”它是基础设施。译成全称反而把概念说窄了。4.3 代码块与链接正文之外的“第二张翻译考卷”代码块里的字符串、变量名、函数名、命令行参数一律不翻注释可以翻示例输出不要翻。这是一条硬规矩。有人会把示例输出里的“error: unexpected token”译成“错误意外的令牌”看起来贴心但读者对照自己终端里的英文报错时反而对不上。链接处理是另一个重灾区。官方文档里的相对链接在中文版里要保持相对结构。如果把目录从英文原版结构改成“按主题重组”所有链接都会断。翻译项目组内一般会加一条“链接自检”步骤发布前用脚本遍历所有相对链接检查目标文件是否存在。# 检查中文版文档里的相对链接是否有效 for f in $(find docs_zh -name *.md); do grep -oP \(\.\.?/[^)]\) $f | tr -d () | while read -r link; do [ -f $(dirname $f)/$link ] || echo BROKEN: $f - $link done done这段脚本扫描docs_zh目录下的所有Markdown文件提取括号形式的相对链接再判断链接指向的文件是否存在输出所有失效项。实际使用时请替换成自己的目录和链接格式。逐行看find拿到文件列表grep提取链接tr剥掉括号dirname拼接出目标路径test判断文件存在性。这个脚本不复杂但能拦下发布前最丢分的一类问题。提示术语表确定后建议把表格放进翻译项目仓库的README同级目录而不是塞进某个角落。团队评审时直接看这一张表就能判断译名风格是否统一。5. MLIR文档翻译的五个常见坑从术语漂移到链接失效的排查这一章是血泪经验汇总。做文档翻译最怕的不是翻错一个词而是系统性踩坑。每一条都按“现象、原因、解决”来写方便你对照自己的项目逐项排查。5.1 术语漂移同一个人写的两章里降级变成下降现象一份中文版资料里Lowering在第一章节译成“渐进式降级”第五章变成“逐步下移”读者以为讲的是两个概念。原因术语表没有在建项初期定下来或者术语表更新后没有同步到所有篇目。多人在不同时段翻译同一份文档时尤其常见各翻各的合入时才发现一堆异名。解决建术语表合入前用脚本扫一遍高频术语。可以先把所有待替换的英文词列出来然后批量找对应的可疑译名。# 扫描可能不一致的译名 grep -rn 下移\|逐步降低\|降级 docs_zh/ | awk -F: {print $3} | sort | uniq -c这段命令把三种可能译法全部统计出来看到分布就能判断哪一种是少数派。awk取冒号后的内容sort和uniq统计出现次数数字异常的译名就是要修正的目标。翻译项目里这种机械扫描能省掉大量人工通读时间。5.2 示例跑不通文档里的命令和仓库源码逻辑对不上现象读者照着文档输入mlir-opt命令报错说找不到某个Pass或者IR语法不匹配示例根本跑不出文档里的输出。原因上游MLIR更新了APIPass改名、方言拆分而翻译文档没有跟随版本更新。文档翻译通常滞后于代码变更这是生态位的天然错位。解决在文档头部钉住上游commit哈希并注明“本中文版基于该commit翻译”。项目内固定用某个MLIR版本做验证所有示例命令都要在CI或本地跑过一遍再标“已验证”。不跑示例就发布的翻译项目很快会被读者用issue淹没。5.3 代码块被中文注释撑变形现象英文注释换成中文后代码块在网页和手机端发生折行语法高亮错乱复制代码时混入多余换行。原因中文字符显示宽度大于英文字符注释一旦写在代码行末尾行长立刻超限。解决中文注释单独占一行不要追加在代码行尾部。注释行长控制在80个字符以内。这条规则要写进翻译项目自己的样式指南否则每次校对都得人工盯。5.4 链接和锚点失效点过去要么404要么跳回英文页现象教程页面里的“下一节”“上一节”链接在中文版里点了没反应或者跳回官方英文页面。原因翻译后文件路径做了调整官方原版的相对链接自然失效。很多人只改了当前文件忘了全站引用它的那些地方。解决保持目录结构与英文原版一致这是最省力的方案。如果一定要重组目录发布前用前面给的链接自检脚本全站扫一遍把全部失效引用一次性修正不要“先发布再补”。5.5 进度追踪不到热情期过了项目停在某个方言文档现象翻译项目做了一半团队热情消退仓库停在“方言”章节再也没动过。原因没有按第一批、第二批、第三批分批也没有可见的进度面板。面对几十万字人的动力会被“看不见终点”消耗掉。解决每章建一个任务卡状态分成“未翻、初翻、术语自查、交叉校对、技术校对、已发布”。发布资源包时只有“已发布”状态的章节可以进正式目录其余一律放草稿目录。这样做的好处是即使项目中途有人离开剩下的章节读者也能立刻看到哪些可信、哪些不能碰。6. 把中文版MLIR资料用起来一条零基础可复现的阅读路径拿到翻译资料后不要从头读到尾。我见过太多零基础读者在“方言”章节反复打转原因不是翻译不好而是阅读顺序不对。MLIR文档是个网状结构线性读会撞墙。建议路径分四步走。第一步读官方教程的中文版重点看“自定义方言”那几章跟着建一个toy方言跑通基础流程。第二步读Rationale和LangRef把“为什么存在方言”“为什么需要多级中间表示”这些设计问题弄懂。第三步读Pass管理器相关章节搞清Pass流水线的调度方式。第四步看代码生成相关文档这时候再看“代码生成”就不会误以为是文本翻译了。验证自己在不在状态最好的办法是动手跑。教程里每个IR片段都应该用mlir-opt验证一遍。# 验证自定义方言IR是否被正确规范化 mlir-opt --canonicalize example.mlirexample.mlir是教程里写的自定义方言示例文件--canonicalize会触发一批转换模式把能折叠的pattern折叠掉。如果文档里的要求是“输出IR的constant值被合并”你看到合并后的IR才算真正理解了那句话。参数说明mlir-opt是MLIR自带的优化工具--canonicalize是它最常用的Pass标志强烈建议把它当成文档翻译的正确性探测器。我的一个教训是第一次读代码生成章节时我始终带着“生成目标代码”的预期结果对着文档里层层下降的IR一脸茫然。后来才明白MLIR的代码生成是IR降级链路的末端描述不是某个一键开关。这个预期调整花掉了比读文档更长的时间。希望帮到你。本文还有配套的精品资源点击获取
简介MLIR官方文档中文翻译项目是一份面向编译器开发者与研究者的完整学习资料适合有一定编译器基础、希望掌握MLIR多级中间表示的中高级开发者全面翻译官方文档与教程系统讲解方言、操作、属性、类型转换、Pass管理器及代码生成等核心机制。资源包共316个文件以89个Markdown译稿为主干辅以41个C头文件、40个C源文件、36个MLIR示例、23个txt说明、15个TableGen定义以及13个SVG示意图等整体仅1.05MB轻量却覆盖完整知识体系。目前已有155人学习。除翻译文本外资源还包含Toy语言示例及多种源码与模式定义文件便于读者对照理解方言注册、IR生成与转换流程从多级中间表示基础设施到具体代码生成技巧均配有详解既能用于自学入门也可作为研发MLIR相关编译器功能时的参考手册。1. MLIR官方文档中文翻译项目它在解决谁的哪一类痛点我见过不少编译器和AI框架工程师打开MLIR官方文档后十分钟内就被“方言Dialect”“操作Operation”“Pass管理器”这些词淹没。MLIR官方文档中文翻译项目要解决的正是这条学习链路上的断点把MLIR官方文档与教程资源逐篇翻译按核心概念、多级中间表示基础设施、方言、操作、属性、类型、转换模式、Pass管理器到代码生成的主线组织成完整的中文学习资料。它适合三类人被英文文档劝退的零基础学习者想快速判断MLIR值不值得引入的框架开发者需要给团队铺内部培训资料的技术负责人。这篇笔记不替你读文档但会给你一套拿到这类翻译资源后怎么组织、怎么读、怎么避坑的方法。2. 读懂MLIR官方文档的骨干多级中间表示、方言与Pass管理器不把概念骨架搭起来就去翻译翻出来的中文大概率没人看得懂这也是许多文档翻译项目翻车的共同原因。MLIR官方文档有一个明显特征它是给“已经知道要做什么”的工程师看的规范不是给新手铺的台阶。每个术语背后都压着一层设计意图。只有先把主干立住再逐句翻译术语才立得住读者才跟得上。2.1 从多级中间表示说起“多级”到底指什么传统编译器里大家熟知的中间表示是单层的。LLVM IR在优化阶段基本保持同一抽象层级C/C前端降下来是什么级别优化就基于什么级别做。MLIR则把“中间表示”本身做成可以组合、可以升降的体系。一个编译流程里可以同时存在多个抽象层级的IR上层做张量运算中层做循环变换下层做寄存器分配每一层都有自己的表示层与层之间通过转换与降级连接。这就是标题里“多级中间表示基础设施”的基本含义。翻译这一段时第一道坎是Lowering这个词的译法。官方文档里progressive lowering反复出现我见过“渐进式降级”“分层下降”“逐步下移”三种译法出现在同一份资料里。我统一用“渐进式降级”第一次出现时标注英文。原因很简单这个词描述的是IR一层层换血的过程不是一次性翻译成目标代码。如果随手译成“降低”读者会误以为是在讲优化级别。这里值得专门说一句MLIR的“代码生成”不是传统意义上“源码翻译成目标代码”的代码生成。很多读者是从C代码生成、PLC代码生成这类业务背景找过来的第一反应是找一个“生成汇编”的开关。但MLIR里的CodeGen是一整套IR逐级变化的过程最终才落到目标后端。翻译官方文档时要把“代码生成”挂到“多级IR的末端”去理解整篇文档的叙事逻辑才会通顺。2.2 方言与操作官方文档里最劝退的两个基础概念Dialect是MLIR组织一切功能的命名空间。官方定义里方言是一组操作、属性和类型的集合。为什么会叫“方言”因为不同领域的人说不同的行话机器学习框架的人说卷积加速器的人说脉动阵列CPU后端的人说寄存器。MLIR允许所有这些行话在同一个IR体系里共存每套行话就是一种方言。文档中出现频率最高的IR片段长这样// 官方教程里反复出现的例子 func.func main() { %cst arith.constant dense[1.0, 2.0] : tensor2xf64 return }这里用了func和arith两个方言。func是函数层方言arith是算术运算方言。%cst是变量名由constant操作产生dense[1.0, 2.0]是属性描述编译期常量tensor2xf64是类型描述数据形状。func.func、arith.constant这种“方言名.操作名”的写法是翻译文档时必须原样保留的部分。翻译这段代码时能动的只有注释。而且注释不能照字面直译成“这是主函数”要译成“主函数入口”。MLIR的func.func并不等价于C语言的main函数它只是一个函数操作。这类细微差别恰恰是文档翻译中最容易埋雷的地方。Operation操作是IR的基本单元文档里经常直接用缩写Op翻译时建议写成“操作Op”后面再单用“操作”即可。2.3 属性、类型、转换模式与Pass管理器翻译时最绕的四组词这四组词需要先明确定义再谈翻译。类型描述的是数据形状比如tensor2xf64属性描述的是编译期就知道的常量信息比如dense[1.0, 2.0]。两者在官方文档里几乎总是成对出现翻译时要注意上下文不能把“attribute”统一译成“属性”就完事在place attribute on operation这类句子里要能看出“给操作挂属性”的动作。Pattern Rewriting在标题里对应“转换模式”。同一概念在一些资料里也叫“模式重写”我建议以标题用的“转换模式”为准但第一次出现时标注英文。MLIR的优化不是写一个大Pass干完所有事而是注册大量小pattern每个pattern只管一类局部变换Canonicalizer就是由无数小pattern驱动的一个Pass流水线实例。Pass这个词我明确建议保留英文不译。译成“趟”“遍”“通行证”都会造成理解障碍。Pass Manager统一译“Pass管理器”。官方文档里还有一个高频组合Pass Pipeline译成“Pass流水线”或“Pass管线”都可以但全篇只能选一个。这里可以做一个速查表方便动笔前建立对应关系传统编译器里的概念MLIR里的对应物翻译注意点优化模式重写Pattern Rewriting不要泛化成“优化流程”指令选择转换Conversion保留“转换”别写成“指令选择”代码生成后端Target 方言结合上下文判断是否指“代码生成”编译选项Pass 流水线选项保留“Pass”字样基本块跳转图控制流图别缩写成“流程图”我见过有翻译把control flow graph直接写成“控制流程图”读者以为是某种业务流程图实际它特指基本块之间的跳转关系。这类词在动笔前不确认后面很难回头改。我的习惯是在2.1到2.3这些核心概念上花两天时间通读英文原文动手翻第一批文档前先把术语表建好而不是边翻边定译名。3. 组织一次MLIR文档翻译范围、流程与版本对齐怎么做翻译MLIR文档和翻译普通开源项目文档不是一回事。它本质上是一个基础设施翻译工程面对的不是二十篇短文而是几十万字、持续变动的规范。没有流程就开工最后一定会烂尾。这一章讲的是怎么把“这个翻译项目值得做”变成“做得完、能用、敢发布”。3.1 先圈定翻译范围官方教程、核心概念还是全部文档常见做法是把范围分成三批来推进。第一批是Getting Started加官方教程教程会带你写一个自定义方言把操作、类型、转换、Pass管理器全部跑一遍这是普通读者最先碰到的入口。第二批是Rationale、LangRef和Pass Infrastructure这些是概念主干的来源也就是标题里“核心概念”和“多级中间表示基础设施”主要覆盖的部分。第三批才是各方言文档和代码生成相关文档比如循环方言、张量方言、GPU方言、LLVM方言这类。判断标准只有一个按“读者从零开始能不能走通”决定先后。第一批的目标是让读者体验“MLIR原来是这么用的”第二批让读者理解“这些设计为什么存在”第三批按需补。我见过不止一个翻译项目一上来就按官网导航顺序从头翻到尾结果翻了两个月还停在概念目录里读者根本没法上手。那是把英文站复制成中文站不是在做学习资料。3.2 术语表先行地基不打后面全是裂缝动手翻第一个文件之前先建一个术语表文件。把标题里出现的技术名词和官方文档里反复出现的词先列一轮。下面这个表可以直接抄走当模板英文建议译名备注状态Dialect方言首次出现标注英文已确认Operation操作缩写Op保留已确认Pass不译编译术语译了反而难懂已确认Pattern Rewriting转换模式不采用“模式重写”已确认Attribute属性注意与Type区分已确认Type类型描述数据形状已确认Lowering降级统一用“渐进式降级”已确认Conversion转换指方言间的转换已确认Canonicalization规范化不要译成“标准化”已确认Bufferization缓冲化指内存缓冲阶段已确认Code Generation代码生成指IR逐级下降后的产物已确认术语表确认后所有篇章共用一份不允许个人单独发挥。翻译过程中发现更好的译名正确的做法是先更新术语表再做一次全局替换而不是只改眼前这篇。全局替换看起来麻烦实际上比“留着以后一起改”省力得多。3.3 翻译流程与分工机器初翻人工校对的四道关卡个人翻译和团队翻译的流程不一样。一个人做的话我的顺序是先用机器翻译产出初稿再通读初稿改成中文表达然后打开英文原版逐段对照最后把文中所有示例命令在本地跑一遍。团队做的话按“初翻、术语自查、交叉校对、技术校对、合并”五步走。技术校对的人选很关键建议找写过MLIR代码的人而不是英语最好的人。术语可以靠表查语义只能靠懂行的人判断。这一步没法外包给纯翻译。我见过一个项目四道校对全做完但技术校对环节没人真跑过mlir-opt结果文档里一半命令行参数是过时的发布后立刻被读者抓包。3.4 版本对齐用commit把“官方文档天天变”钉住MLIR文档不是独立站点它和LLVM项目源码在同一个仓库里发布。今天翻完的LangRef下个月可能就被上游改动。不对齐版本读者照着文档操作发现源码对不上信任感会立刻归零。做法是四步。第一在翻译项目里记录上游commit哈希。第二每个翻译文件头部标注“基于commit xxxx翻译”。第三定期用git log对比上游文档变动。第四发布资源包时把版本信息写进README。记录上游版本可以用这条命令# 在翻译项目里记录上游版本 git log -1 --format%H -- docs/LangRef.rst命令从仓库里找出最后一次修改LangRef文档的commit哈希把输出结果写进翻译项目的版本说明文件。这样读者一旦发现文档和源码对不上能立刻知道是上游更新了还是翻译本身出错。参数说明--format%H表示只输出完整哈希--后面跟文件路径表示只看该文件的提交记录。没有人愿意用一份不知道对应什么版本的文档这是文档翻译项目最容易忽略却最影响口碑的一环。4. MLIR文档术语对照表十六个关键词的译名与取舍逻辑术语表是一份文档翻译项目的黑匣子读者看不到但每句话的背后都有它。这一章把MLIR官方文档里最高频的十六组词列出来给出推荐译名和取舍理由可以直接拿去做团队评审的讨论底稿。4.1 推荐译名表先统一再开翻英文术语推荐译名取舍说明MLIRMLIR整体保留不译成“多级中间表示语言”Multi-Level多级指抽象层级的数量Intermediate Representation中间表示不缩写为“IR”单用Infrastructure基础设施标题用语保留Dialect方言首次出现标注英文Operation操作文档中Op缩写保留Attribute属性与类型并列出现Type类型不要译成“种类”Pass不译译成“趟”或“遍”都奇怪Pass ManagerPass管理器固定搭配Pattern Rewriting转换模式备选“模式重写”但全篇统一Lowering降级固定搭配“渐进式降级”Conversion转换方言与方言之间的变换Canonicalization规范化不要写成“标准化”Bufferization缓冲化指定进内存缓冲阶段Code Generation代码生成注意是IR级生成这张表的逻辑不是“每个词都要找一个中文对应”而是“哪些词翻译了反而增加理解成本”。Pass和MLIR属于后者保留英文的收益远大于翻译。4.2 哪些词必须保留英文Pass、Dialect、Op的取舍Pass是我第一个坚持不译的词。中文编译资料里它常被译成“趟”“遍”“通行证”读者看到“一遍遍跑”完全无法建立专业对应。不如直接写Pass让读者在中文语境里记住这个英文单词。Dialect的译名“方言”本身是意译不是音译第一次出现写成“方言Dialect”后面单用“方言”即可。Op这个缩写也建议保留。官方文档里“Op”的出现频率远高于“Operation”翻译成“操作”没问题但遇到“Op traits”“Op interface”这类复合结构时建议译成“操作特征”“操作接口”第一次出现标注“操作Op”。不一致的写法会出现在同一句话里“这个Op的操作数”这种表达就是没核对术语表的典型症状。MLIR本身更不需要翻译。有些资料会写成“多级中间表示语言”看起来是把全称翻译了一遍但MLIR并不是一种传统意义上的“语言”它是基础设施。译成全称反而把概念说窄了。4.3 代码块与链接正文之外的“第二张翻译考卷”代码块里的字符串、变量名、函数名、命令行参数一律不翻注释可以翻示例输出不要翻。这是一条硬规矩。有人会把示例输出里的“error: unexpected token”译成“错误意外的令牌”看起来贴心但读者对照自己终端里的英文报错时反而对不上。链接处理是另一个重灾区。官方文档里的相对链接在中文版里要保持相对结构。如果把目录从英文原版结构改成“按主题重组”所有链接都会断。翻译项目组内一般会加一条“链接自检”步骤发布前用脚本遍历所有相对链接检查目标文件是否存在。# 检查中文版文档里的相对链接是否有效 for f in $(find docs_zh -name *.md); do grep -oP \(\.\.?/[^)]\) $f | tr -d () | while read -r link; do [ -f $(dirname $f)/$link ] || echo BROKEN: $f - $link done done这段脚本扫描docs_zh目录下的所有Markdown文件提取括号形式的相对链接再判断链接指向的文件是否存在输出所有失效项。实际使用时请替换成自己的目录和链接格式。逐行看find拿到文件列表grep提取链接tr剥掉括号dirname拼接出目标路径test判断文件存在性。这个脚本不复杂但能拦下发布前最丢分的一类问题。提示术语表确定后建议把表格放进翻译项目仓库的README同级目录而不是塞进某个角落。团队评审时直接看这一张表就能判断译名风格是否统一。5. MLIR文档翻译的五个常见坑从术语漂移到链接失效的排查这一章是血泪经验汇总。做文档翻译最怕的不是翻错一个词而是系统性踩坑。每一条都按“现象、原因、解决”来写方便你对照自己的项目逐项排查。5.1 术语漂移同一个人写的两章里降级变成下降现象一份中文版资料里Lowering在第一章节译成“渐进式降级”第五章变成“逐步下移”读者以为讲的是两个概念。原因术语表没有在建项初期定下来或者术语表更新后没有同步到所有篇目。多人在不同时段翻译同一份文档时尤其常见各翻各的合入时才发现一堆异名。解决建术语表合入前用脚本扫一遍高频术语。可以先把所有待替换的英文词列出来然后批量找对应的可疑译名。# 扫描可能不一致的译名 grep -rn 下移\|逐步降低\|降级 docs_zh/ | awk -F: {print $3} | sort | uniq -c这段命令把三种可能译法全部统计出来看到分布就能判断哪一种是少数派。awk取冒号后的内容sort和uniq统计出现次数数字异常的译名就是要修正的目标。翻译项目里这种机械扫描能省掉大量人工通读时间。5.2 示例跑不通文档里的命令和仓库源码逻辑对不上现象读者照着文档输入mlir-opt命令报错说找不到某个Pass或者IR语法不匹配示例根本跑不出文档里的输出。原因上游MLIR更新了APIPass改名、方言拆分而翻译文档没有跟随版本更新。文档翻译通常滞后于代码变更这是生态位的天然错位。解决在文档头部钉住上游commit哈希并注明“本中文版基于该commit翻译”。项目内固定用某个MLIR版本做验证所有示例命令都要在CI或本地跑过一遍再标“已验证”。不跑示例就发布的翻译项目很快会被读者用issue淹没。5.3 代码块被中文注释撑变形现象英文注释换成中文后代码块在网页和手机端发生折行语法高亮错乱复制代码时混入多余换行。原因中文字符显示宽度大于英文字符注释一旦写在代码行末尾行长立刻超限。解决中文注释单独占一行不要追加在代码行尾部。注释行长控制在80个字符以内。这条规则要写进翻译项目自己的样式指南否则每次校对都得人工盯。5.4 链接和锚点失效点过去要么404要么跳回英文页现象教程页面里的“下一节”“上一节”链接在中文版里点了没反应或者跳回官方英文页面。原因翻译后文件路径做了调整官方原版的相对链接自然失效。很多人只改了当前文件忘了全站引用它的那些地方。解决保持目录结构与英文原版一致这是最省力的方案。如果一定要重组目录发布前用前面给的链接自检脚本全站扫一遍把全部失效引用一次性修正不要“先发布再补”。5.5 进度追踪不到热情期过了项目停在某个方言文档现象翻译项目做了一半团队热情消退仓库停在“方言”章节再也没动过。原因没有按第一批、第二批、第三批分批也没有可见的进度面板。面对几十万字人的动力会被“看不见终点”消耗掉。解决每章建一个任务卡状态分成“未翻、初翻、术语自查、交叉校对、技术校对、已发布”。发布资源包时只有“已发布”状态的章节可以进正式目录其余一律放草稿目录。这样做的好处是即使项目中途有人离开剩下的章节读者也能立刻看到哪些可信、哪些不能碰。6. 把中文版MLIR资料用起来一条零基础可复现的阅读路径拿到翻译资料后不要从头读到尾。我见过太多零基础读者在“方言”章节反复打转原因不是翻译不好而是阅读顺序不对。MLIR文档是个网状结构线性读会撞墙。建议路径分四步走。第一步读官方教程的中文版重点看“自定义方言”那几章跟着建一个toy方言跑通基础流程。第二步读Rationale和LangRef把“为什么存在方言”“为什么需要多级中间表示”这些设计问题弄懂。第三步读Pass管理器相关章节搞清Pass流水线的调度方式。第四步看代码生成相关文档这时候再看“代码生成”就不会误以为是文本翻译了。验证自己在不在状态最好的办法是动手跑。教程里每个IR片段都应该用mlir-opt验证一遍。# 验证自定义方言IR是否被正确规范化 mlir-opt --canonicalize example.mlirexample.mlir是教程里写的自定义方言示例文件--canonicalize会触发一批转换模式把能折叠的pattern折叠掉。如果文档里的要求是“输出IR的constant值被合并”你看到合并后的IR才算真正理解了那句话。参数说明mlir-opt是MLIR自带的优化工具--canonicalize是它最常用的Pass标志强烈建议把它当成文档翻译的正确性探测器。我的一个教训是第一次读代码生成章节时我始终带着“生成目标代码”的预期结果对着文档里层层下降的IR一脸茫然。后来才明白MLIR的代码生成是IR降级链路的末端描述不是某个一键开关。这个预期调整花掉了比读文档更长的时间。希望帮到你。本文还有配套的精品资源点击获取
