内容摘要：打开 MyBatis 官网，右上角语言选项里有“简体中文”。点进去，你会发现一个尴尬的事实：大部分核心页面还是英文。所谓“中文文档”，其实是社区翻译的阶段性成果，版本滞后、术语不统一、部分段落直接机翻

打开 MyBatis 官网，档中右上角语言选项里有“简体中文”。档中点进去，档中你会发现一个尴尬的档中事实：大部分核心页面还是英文。所谓“中文文档”，档中其实是档中社区翻译的阶段性成果，版本滞后、档中术语不统一、档中部分段落直接机翻。档中我去年帮一个团队排查 `@SelectProvider` 的档中用法，官方中文页面的档中示例代码里参数名和英文版对不上，照着写直接报 `BindingException`。档中这不是档中个例。

MyBatis 的档中中文文档入口在 `mybatis.org/mybatis-3/zh_CN/`。首页的档中“入门”章节翻译得还算完整，安装、SqlSessionFactory、XML 映射器这些基础内容能看。但往下翻，动态 SQL 的 `` 属性表里，“collection”被译成“集合”，可代码示例里又保留英文原词，读起来像夹生饭。更麻烦的是“Java API”那一节，中文版只列了方法签名，参数说明直接砍掉。想查 `SqlSession.selectList` 的重载细节？只能切回英文。

翻译质量参差背后是维护机制的问题。MyBatis 的中文文档没有独立的版本分支，翻译者通过 GitHub 提交 PR，合并后跟英文版同步发布。但英文文档本身更新就慢，3.5.x 系列有些新特性——比如 `@Flush` 注解——英文页面上线半年后中文才补上。社区里有人提 issue 问“为什么中文文档没有 `CachingExecutor` 的说明”，维护者回复“欢迎提交翻译”。说白了，这是志愿者驱动，不是官方本地化团队。

实际开发中，中文文档最大的价值在“入门”和“XML 配置”两块。`` 标签的各个属性，中文版给了表格，`cacheEnabled`、`lazyLoadingEnabled` 这些开关的作用写得比英文还细。但一碰到 `TypeHandler` 注册、`Plugin` 拦截器签名这种进阶内容，中文页面要么缺失，要么只给个链接跳回英文。我见过有开发者把中文文档的 `ResultMap` 示例直接贴进项目，结果 `` 的 `columnPrefix` 属性在中文版里根本没提，调试了一下午。

那怎么用？我的习惯是：基础配置查中文，快速定位；API 细节和异常排查切英文。英文文档的搜索功能也更好用，`Ctrl+F` 找 `ExecutorType` 能直接跳到 `Configuration` 类的说明，中文版经常只翻译了标题。另外，MyBatis-Plus 的中文文档倒是完整，但那是另一个项目，别搞混。

有个细节值得说：中文文档的“日志”章节里，`logImpl` 的取值列表把 `SLF4J` 写成了 `SLF4J`（正确），但 `JDK_LOGGING` 被译成“JDK 日志”，实际配置时得写 `JDK_LOGGING`。这种“翻译了但没完全翻译”的地方，新手很容易踩坑。我的建议是，把中文文档当“导读”，真正写代码时开着英文页面。别指望它替你省掉查 API 的功夫。

最后提一句，如果你真想贡献翻译，GitHub 上 `mybatis-3` 仓库的 `docs/zh_CN` 目录欢迎 PR。但先读一遍 `CONTRIBUTING.md`，里面明确说了：不要机翻，术语要跟现有译文保持一致。我提交过一个小节，被要求改了三次措辞。这活儿不轻松，但比抱怨文档烂强。