代码注释翻译工具有哪些
当前市面上占据主流地位的代码注释翻译工具，每一款都具备各自独特的特性。像IDE所自带的插件，就以VS Code里面的“Comment Translate”为例，这个插件能够通过一键操作的方式，将注释进行选中，进而调用微软翻译API，它支持二十多种语言之间的相互转换，其安装量已然超过了百万。除此之外，还存在专业级别的工具，比如“Transifex”，它主要是面向团队协作方面，能够针对整份代码文件里的注释，开展批量术语的管理以及审校流程。针对轻量需求而言，开源项目“i18n-comments”，它能够借助Python脚本去调用百度翻译接口，在编译之前就自动替换注释文本，它是适合持续集成环境的。
除了上述那些工具之外，在线平台像DeepL是有桌面客户端的，它支持粘贴代码片段并且保留原来的缩进格式。最为贴近实际情况的方式是运用浏览器扩展“划词翻译”，在GitLab或者GitHub网页上直接通过鼠标选取注释就能显示译文。不过需要注意的是，免费工具一般是有字符数限制的，而企业级工具比如“Crowdin”是按照代码仓库来收费的，但是它能够智能识别注释与代码字符串，以此避免误译变量名。进行选择的时候建议先去试用一番之后再做决定。
注释翻译影响代码运行吗
注释本身，在编译阶段，或者解释阶段，会被完全忽略掉，所以，翻译注释，绝对不会改变程序逻辑，或者运行结果。不管是Python，还是Java，又或者是C++，注释内容，仅仅作为工程师的阅读标记，不参与语法解析。但是，需要特别警惕一种情况：某些动态语言，像是JavaScript的eval函数，或者PHP的assert语句，如果意外把注释内容当作字符串执行，那么可能会抛出异常，尽管这属于糟糕的编码实践。所以，翻译之前，最好用正则检查一下，是否有eval引用注释变量。
更安全的做法是，仅翻译纯粹的文档注释块，让代码行内的尾随注释维持不变。另外，对于像Javadoc或Sphinx格式的结构化注释，在翻译时要留意保留标签，比如@param以及返回值类型，不然会影响API文档生成工具。总之，只要不涉及代码字符串区域，翻译注释是不存在风险的。建议在翻译之后运行一遍单元测试，凭借事实消除团队成员的疑虑。
如何保证翻译的准确性
技术文档翻译里最大的那个坑是专业术语存在歧义，像“pool”它在线程池当中被译成“池”，然而在内存池里却有可能译成“缓存池”，解决方案那便是建立项目术语表这件事儿。这是通过自定义字典来强制工具统一对应的译法工作，对于机器学习类项目而言，要提前把“tensor”“backpropagation”等这些词加入忽略列表，以此来保持原文状态。同时要优先去采用微软或者是Google的技术文档术语库，比如说“方法”对应的是“method”而不是“函数”。
不可替代的是人工进行的二次校验，把翻译后的注释朝着相反方向译回英文，再跟原注释作对比，这样能够迅速发觉语义漂移，像将“exception thrown”错误地译成“异常抛出”，而实际上应该是“抛出的异常”这种常见错误就会被发现，建议小组指定一名技术英语水平较好的成员去做抽检，重点对条件判断、算法逻辑相关的注释展开核查，要是使用机器翻译之后再借助Grammarly修改被动语态以及长难句，那么准确率能够提高到95%以上。
中英文注释混排怎么处理
众多遗留代码有着中英文注释混杂的状况，像是函数说明采用英文，变量注释运用中文。强行统一成单一语言耗费时间极大，推荐采取折中方案：留存所有原来的注释，在其下方增添译文行并凭借特殊标记如“[CN]”去区分。这样既能够契合国内团队阅读需求，又方便外籍同事理解。VSCode插件“Bilingual Comments Generator”能够自动为选中的英文注释生成出中文翻译行，并且调整缩进使其对齐。
更为彻底的方案乃是把语言标记归入注释规范之中，规定业务逻辑注释必须中英两种语言同时存在，技术实现注释仅仅需要一种语言即可，在代码审查阶段对新增的单一语言注释予以拦截，对于早就已经混排的文件能够利用脚本寻觅出未配对的注释行，之后调用翻译API进行批量补全，留意Markdown格式的注释要留存表头以及列表结构，防止破坏嵌入的链接或者代码示例，混排处理要是得当反倒能够成为团队的文档资产。
团队协作注释翻译规范
在存在多人协作情形下的代码库里面，注释翻译这件事是一定要遵循统一约定的。首先呢，要在项目的根目录那儿放置TRANSLATION.md文件，以此规定注释语言的优先级，具体是国内团队在内部使用简体中文，而开源仓库是中英双语的状态，不过核心模块的算法注释必须得有英文版。其次呢，Git提交钩子会自动去检查新增注释里是不是包含没有翻译的片段，要是超过百分之二十的非代码行都缺少译文，那就会拦截推送并且提醒开发者去补充。
进行代码审查之际，增添注释翻译质量检查这一项目。参照Google的工程实践做法，规定每个类的头部注释得是中英双语形式，函数注释起码要完整地描述参数以及返回值。每周轮流安排一名翻译校对员，其职责是把可疑的机器翻译转变为自然的技术表达。为了将维护成本降低，可以配置CI流水线，使其每晚针对变动注释开展机器翻译并创建候选译文分支，让团队能够快速地进行审阅与合并。规范落实之后，注释翻译不再是额外的负担，而是质量方面的标杆。
自动化翻译注释的优缺点
自动化翻译注释具备的最大优点在于速度极其快，针对十万行级别的历史代码库而言，全量翻译仅仅需要十分钟。与此同时保证了风格的一致性，不存在人工翻译经常出现的术语前后不一致的情况。GitHub Actions上存在现成的工作流，每次push之后会自动翻译新增注释并且生成语言包文件，开发者几乎没有什么感知。针对使用国际化框架的项目，还能够把注释抽离成JSON键值对，在运行的时候动态加载对应语言，从而节省编译体积。
它的缺点也是相当显著的：由于机器没办法理解由上下文逻辑所引发的幽默、吐槽或者临时标记（就像FIXME这样的）。曾经存在一个项目，该项目把“hack for IE”翻译成为“为IE破解”，从而致使新成员误以为进行了漏洞攻击。除此之外，自动化翻译极易破坏内嵌于代码示例里的缩进以及特殊符号，进而让示例无法执行。更为严重的在于，如果不小心把调试用的注释打印日志代码里的字符串进行了翻译，那么就有可能改变输出内容。所以呢，自动化仅仅能够当作初稿，最终必定得经过人工抽查起码10%的译文。平衡效率与准确，才是成熟团队的选择。
你有没有碰到过那种，由于注释语言杂乱无章，致使调试耗费了许久时间的程序漏洞呢？欢迎于评论区域分享你的相关经历，点个赞以便让更多开发者能够避开掉入陷阱的情况。
原创文章，作者：有道翻译，如若转载，请注明出处：https://fanyi-youdao.net/archives/1250
