2026/9/17 3:22:49
FEATURED · 精选文章 
简介Java17中文文档HTML版是一份完整的中文API参考手册面向Java初学者和有经验的开发人员覆盖Java17语法、标准库、类API及开发工具说明可帮助读者了解新功能、改进与重要更新并指导如何构建高效、可靠且安全的应用程序。资源压缩包约六十五点六MB解压后文件总数超过一万个其中以10205个HTML页面构成文档主体另含CSS样式表、SVG图标、JavaScript脚本、字体文件及少量说明文档整套内容可在浏览器中离线检索和阅读。目前已有八十九人浏览学习。文档按模块清晰组织每个API页面均附有类与接口说明、字段及构造器摘要、方法参数与返回值细节支持目录树快速跳转配套样式与前端脚本让页面布局规范、搜索便捷。无论用于系统学习还是日常查阅这套中文资料都能大幅降低理解门槛是掌握Java17的重要参考。1. 为什么 Java17 中文文档要单独做成 HTML 版本如果你们团队刚把项目从 Java 8 迁到 Java 17又恰好是在内网环境开发多数人会先遇到一个落差官方发布的 Java 17 文档只有英文 HTML下载安装完 JDK 之后IDE 内置的 JavaDoc 解析结果要么不全要么全是英文条目。查一个java.nio.file.Files.readString的异常说明要点进五六层页面还得在浏览器里开翻译插件既慢也不方便同事复用。所以标题里的“Java17 中文文档 HTML 版本”指的并不是某个开箱即用的官方中文发布包而是一套把官方 JavaDoc 页面本地化、离线化、且仍然保持 HTML 网页可检索形态的做法。它解决三个问题中文阅读、离线访问、页面间可跳转检索。适合两类人一类是想在公司内网搭 Java 17 API 文档站的运维或架构工程师另一类是希望边写代码边查证 Java 17 新特性的开发人员。这个工作看起来只是“翻译一堆网页”实际上牵涉 HTML 字符编码、JavaDoc 生成参数、索引文件的离线检索机制以及浏览器打开方式的选型。下文把这条路一次性说透照着做能拿到一份可发给同事的离线版中文 HTML 文档。2. Java17 官方 HTML 文档的结构离线可搜的 JavaDoc 产物要本地化一份文档先要摸清它的目录结构和渲染机制。Java 17 的官方文档不是单一 PDF而是一个多模块页面树api/java.base/java/lang/String.html、api/java.base/java/util/List.html这类路径对应的是java.base模块下的类页面index-files目录存放所有索引页search.js、type-search-index.js、member-search-index.js、tag-search-index.js这组文件则支撑页面顶部搜索框的离线检索。HTML 版本之所以比 Markdown 或 PDF 更适合做中文文档是因为 JavaDoc 生成器已经把所有类、方法、字段的跳转关系编译成了静态链接翻译时只需要替换页面正文文字链接结构可以原样保留。这意味着你可以在不重写站点架构的前提下把一份官方英文 HTML 文档批处理成中文 HTML 文档。2.1 从 JDK 17 发布渠道提取离线文档两条路径常见做法有两种取决于你手上有什么。第一种是从官方发布渠道获取与当前 JDK 版本匹配的离线文档归档解压后得到完整的英文 HTML 页面# 假设你已经把文档归档放到 /opt/java17-docs/ mkdir -p /data/workspace/zh-jdk17-docs cd /data/workspace/zh-jdk17-docs unzip /opt/java17-docs/jdk-17.0.12_doc-all.zip find . -maxdepth 2 -type d | head -20这里doc-all.zip解压出来通常包含api、specs、legal等目录其中api就是后续要本地化的主战场。注意归档版本要和线上 JDK 的小版本尽量对齐比如生产环境是 17.0.12就下载对应版本的文档避免接口签名差异造成误导。第二种路径是直接从 JDK 安装目录带出的src.zip自己生成 HTML 文档。这种方式的好处是文档与线上 JDK 完全同源缺点是需要先处理模块源码路径。适合那些连文档归档都不方便获取、但已经有完整 JDK 的环境具体命令见下一节。2.2 用 javadoc 自己构建一份 HTML 版本如果你已经安装了 java17并且能在命令行跑通javadoc可以跳过下载步骤直接对 JDK 附带的源码生成 HTML 文档。先把src.zip解压到工作目录再做模块化构建mkdir -p /data/jdk17-src cd /data/jdk17-src unzip -q $JAVA_HOME/lib/src.zip -d src cd src javadoc \ --release 17 \ -d /data/workspace/zh-jdk17-docs/api \ -locale zh_CN \ -encoding UTF-8 \ -charset UTF-8 \ -docencoding UTF-8 \ -Xdoclint:none \ --module-source-path . \ --module java.base,java.sql,java.naming,java.desktop,java.net.http这条命令里几个参数的含义--release 17表示按 Java 17 的 API 表面生成文档不会因为本地 JDK 是更高版本而带出新 API-locale zh_CN让生成器把“Overview”“Package”这类框架文字渲染成中文但类注释和方法说明仍是源码里的英文原文-encoding、-charset、-docencoding三个参数统一输入和输出编码缺一个都可能在后续批处理时出现中文乱码-Xdoclint:none关闭文档规范检查避免因为源码注释里的 HTML 标签不规范导致整个构建中断。生成完毕后api目录下会出现index.html、overview-tree.html、constant-values.html、serialized-form.html等标准文件搜索框依赖的search.js也会一并生成。这一步验证通过说明整套 HTML 版本可以在本地复现后续中文替换只是内容层操作不会破坏结构。2.3 search.js 与索引文件HTML 版本自带的离线检索Java 17 的 JavaDoc 页面顶部搜索框并不是请求外部搜索引擎而是读取本地生成的索引文件。type-search-index.js存了所有类名和接口名member-search-index.js存了所有字段和方法名tag-search-index.js存了since、deprecated这类标签信息搜索时由search.js在前端做模糊匹配。这带来一个对本地中文文档很关键的限制索引文件里的英文条目必须保留不能为了“全中文”把索引里的类名也翻译掉。正确做法是只翻译页面展示文案索引保持英文原样这样中文读者搜Files或readString仍然能命中。同理index-files目录下的按字母索引页可以保留英文标题但可以在标题旁补充中文模块名说明。理解了这套结构接下来就能动本地化改造了。不要试图重新发明文档站JavaDoc 生成器已经替你把最难的部分做完了。3. 把英文 HTML 文档本地化成中文的五步做法拿到干净的官方 HTML 版本之后本地化不是逐页手工翻译而是按文件类型分层处理。JavaDoc 页面里的文案分三类框架栏文字“Overview”“Package”“Class”、注释正文div.block里的说明、签名部分member-signature里的方法名和参数。三类文案的替换策略完全不同下面的步骤按执行顺序展开。3.1 先统一编码与 lang 属性html 标签层面的预处理官方英文文档的 HTML 标签里声明的是langen部分老资源还是单字节编码。如果不先统一成 UTF-8 并把语言标记改成zh-CN后面替换中文时浏览器会按错误编码解析导致乱码而且无障碍阅读器和搜索引擎都会把文档识别成英文。cd /data/workspace/zh-jdk17-docs/api # 把所有 HTML 文件统一转为 UTF-8 无 BOM 格式 find . -name *.html -type f -exec sed -i s/html langen/html langzh-CN/g {} \; # 检查是否还有残留的 langen grep -rl langen . | head -5这里用sed -i直接原地替换配合find -exec遍历整个目录树。如果原始文件是 ISO-8859-1 编码需要先用iconv -f ISO-8859-1 -t UTF-8做转换再执行替换否则高字节字符会被截断。替换完成后打开任意页面查看源码确认html langzh-CN和meta charsetUTF-8同时存在这一步是所有后续替换的地基。3.2 复用中文术语表替换 API 文案JavaDoc 的注释正文有固定结构英文方法说明通常以Returns、Throws、Parameters、Specified by开头。这些结构词可以直接映射成中文术语用正则做批量替换不需要人工上下文判断。cd /data/workspace/zh-jdk17-docs/api # 按优先级替换先替换长短语再替换单词避免子串误伤 sed -i \ -e s/Specified by:/实现自/g \ -e s/Overrides:/覆盖自/g \ -e s/Parameters:/参数/g \ -e s/Returns:/返回/g \ -e s/Throws:/抛出/g \ -e s/Since:/始于版本/g \ -e s/See Also:/另见/g \ -e s/Default Value:/默认值/g \ $(find . -name *.html)注意替换顺序Returns:必须先于任何更短的模式执行否则如果某个类名里恰好包含这个单词会被误替换。翻译正文里的完整句子时一个更稳妥的做法是用 Python 解析出div.block内容做对照翻译而不是全局替换。因为全局sed可能污染方法名和类名比如java.lang.ProcessHandle里的Handle不能翻成“句柄”。术语表方式适合结构性短语完整句子建议走机器翻译后再人工校对把结果按文件路径回写到对应 HTML 里。3.3 不要用“html 转 md”再转回 HTML 的偷懒方案有些团队为了省事先写脚本把 HTML 转成 Markdown 翻译完再转回 HTML这种做法在这里会毁掉整份文档。JavaDoc 页面里的a href跳转、code内联代码、pre签名块和id锚点在 Markdown 往返转换后会出现三类问题相对链接的层级关系丢失、member-search-index.js里的锚点与页面id对不上、pre里等宽字体样式被压平。如果确实需要批量提取正文去翻译正确做法是只提取文本不进原文。用 Python 的 HTMLParser 把div.block内的纯文本抽出来翻译译完再按原路径写回对应节点结构标签一个都不动。搜索索引文件search.js和各类*-search-index.js完全不要碰它们是英文原版结构的一部分。3.4 示例代码与说明文字同步翻译HTML 页面里除了 API 注释还有example相关段落和使用示例代码块。代码块内的方法名、变量名要保持英文原名但注释要翻译。这里可以用一个简单的 Python 脚本按文件批量处理import re from pathlib import Path def translate_pre_comments(text: str) - str: 把 pre 代码块里的 // 英文注释替换成中文行号与缩进不变 def repl(match): block match.group(0) lines [] for line in block.splitlines(): if line.strip().startswith(//): # 这里接你的术语对照表示例化实现 line re.sub(r//\s*(.*), lambda m: f// {TERMS.get(m.group(1), m.group(1))}, line) lines.append(line) return \n.join(lines) return re.sub(rpre.*?/pre, repl, text, flagsre.S) for html_file in Path(/data/workspace/zh-jdk17-docs/api).rglob(*.html): content html_file.read_text(encodingutf-8) content translate_pre_comments(content) html_file.write_text(content, encodingutf-8)这段脚本用正则匹配pre块逐行处理//开头的注释。TERMS字典可以维护成业务词汇表比如creates a new file - 创建新文件。逻辑重点在于只动注释行不动代码本身写成文件回写而不是打印预览是为了便于 git diff 查看每一步改动。4. 生成“Java17中文文档”时的必调参数与排错本地化过程中真正耗时间的不是翻译而是各种环境不一致导致的构建和预览问题。下面按参数、预览方式、高频报错三条线展开每一条都是实际改动时容易踩的坑。4.1 javadoc 命令里 4 个影响中文输出的参数自定义构建时下面的参数表建议直接保存成构建脚本的固定配置参数作用不设置的后果-locale zh_CN生成器自带按钮、标签显示为中文框架部分仍是英文-encoding UTF-8指定源码读取编码源码注释里的中文读取乱码-charset UTF-8指定生成页面字符集浏览器自动识别成 GBK 或 ISO-8859-1-docencoding UTF-8指定最终 HTML 文件编码HTTP 响应头与文件实际编码不一致其中最容易忽略的是-locale zh_CN与-docencoding UTF-8的配合。前者只影响生成器输出的 UI 文案后者影响所有页面文件的落盘编码两个都设了中文才能稳定显示。如果是在 Windows 环境执行路径含有空格时整个命令要在 PowerShell 里用--%或把路径用双引号包裹避免 javadoc 把路径拆分。4.2 本地预览必须走 HTTPfile:// 会触发搜索失效文档本地化完成后第一步验证应该是启动本地 HTTP 服务而不是双击index.html。原因在于search.js在 Java 17 的 JavaDoc 里使用fetch加载索引文件而fetch在file://协议下会被浏览器拦截表现为搜索框输入后无任何结果。cd /data/workspace/zh-jdk17-docs python3 -m http.server 8080 --bind 0.0.0.0启动后访问http://localhost:8080/api/index.html。浏览器地址必须是 HTTP 协议且页面上能搜到Files、List等类名。这个 Python 命令把当前目录作为站点根目录--bind 0.0.0.0是让同网段同事也能访问仅本机预览时可以去掉。4.3 高频报错乱码、路径带空格、doclint 中断乱码的排查顺序是先看 HTMLmeta声明再看 HTTP 响应头最后看源文件字节。三者必须一致都是 UTF-8。很多场景下源码注释里混入了 GBK 编码的中文字符-encoding UTF-8会直接报“编码 UTF-8 的不可映射字符”这时用iconv -f GBK -t UTF-8单独转码对应源文件而不是改全局参数。路径带空格是 Windows 下的常见错误javadoc会把C:\Program Files\...按空格拆成两个参数报javadoc: error - Illegal package name。解决方法是把整个输出的-d路径和模块路径都放进引号或者在目录名里避免空格。doclint 中断则是最隐蔽的某些第三方源码注释里的{link}标签引用了不存在的类javadoc默认会报错退出。构建工具链里加上-Xdoclint:none只输出文档不校验注释规范即可绕开这种与本地化无关的构建碎片问题。4.4 用一张表记住常见问题与排查命令问题现象可能原因排查命令搜索框无结果用 file:// 打开改用python3 -m http.server预览页面中文变问号编码参数未统一file -i index.html查看字符集-encoding报错源文件混入 GBKiconv -l | grep GBK确认可用编码后转换生成过程中断doclint 校验失败检查输出里的error:行加-Xdoclint:none方法跳转 404链接层级被改写find . -name *.html | wc -l对比替换前后文件数这一轮排错做完文档基本能在本机稳定访问。接下来是把这份成果接入开发环境的日常流程让它真正替代浏览器查英文文档的习惯。5. 把中文 HTML 文档接进 IDE 与批量校验的技巧文档做得再好如果不接入 IDE 的 JavaDoc 查看面板使用频率会大大降低。以 IntelliJ IDEA 为例在Project Structure的 SDK 配置里选中 JDK 17 后把Documentation Paths指向本地api/index.html即可。之后鼠标悬停在Files.readString上弹出的 Javadoc 面板显示的就是本地中文版本无需联网。这一招也适用于 Eclipse配置位置在Window - Preferences - Java - Installed JREs里选中 JDK 后点击Javadoc按钮修改。接入 IDE 后还要验证翻译是否漏掉了一大片。用 ripgrep 统计残留英文结构词比人工抽查覆盖率更可靠cd /data/workspace/zh-jdk17-docs/api # 统计还有多少页面残留英文 Returns: 结构词 rg -l Returns: --glob *.html | wc -l # 统计包含中文的页面数量 rg -l [\x{4e00}-\x{9fff}] --glob *.html | wc -l两条命令的差值就是还没覆盖的页面。如果差值很大优先检查serialized-form.html和constant-values.html这类非 API 页面容易被批处理脚本漏掉。更细的校验是检查所有页面里是否有互斥的langen和langzh-CN并存说明替换脚本没有跑遍全部文件。最后做一次链接完整性检查确保没有因为批量替换把相对路径写坏。用 Python 脚本遍历所有 HTML 页面收集href断言目标文件存在import re from pathlib import Path from urllib.parse import urlparse, unquote api Path(/data/workspace/zh-jdk17-docs/api) broken [] for html in api.rglob(*.html): for href in re.findall(rhref([^]), html.read_text(encodingutf-8)): target unquote(urlparse(href).path) if target.startswith(http) or target.startswith(#) or :// in target: continue if not (api / target).exists(): broken.append(f{html.relative_to(api)} - {target}) print(fbroken links: {len(broken)}) for item in broken[:20]: print(item)这段脚本跳过外链和页面内锚点只检查本地相对链接。跑完输出为空说明整套 HTML 文档的内部跳转完好。注意脚本里特意排除了://的绝对地址因为在离线文档环境里出现绝对域名链接就意味着页面会尝试请求外网资源这也是本地化后最容易被忽略的一处残留。本文还有配套的精品资源点击获取
Java17中文文档HTML版制作：离线本地化与IDE接入实践
简介Java17中文文档HTML版是一份完整的中文API参考手册面向Java初学者和有经验的开发人员覆盖Java17语法、标准库、类API及开发工具说明可帮助读者了解新功能、改进与重要更新并指导如何构建高效、可靠且安全的应用程序。资源压缩包约六十五点六MB解压后文件总数超过一万个其中以10205个HTML页面构成文档主体另含CSS样式表、SVG图标、JavaScript脚本、字体文件及少量说明文档整套内容可在浏览器中离线检索和阅读。目前已有八十九人浏览学习。文档按模块清晰组织每个API页面均附有类与接口说明、字段及构造器摘要、方法参数与返回值细节支持目录树快速跳转配套样式与前端脚本让页面布局规范、搜索便捷。无论用于系统学习还是日常查阅这套中文资料都能大幅降低理解门槛是掌握Java17的重要参考。1. 为什么 Java17 中文文档要单独做成 HTML 版本如果你们团队刚把项目从 Java 8 迁到 Java 17又恰好是在内网环境开发多数人会先遇到一个落差官方发布的 Java 17 文档只有英文 HTML下载安装完 JDK 之后IDE 内置的 JavaDoc 解析结果要么不全要么全是英文条目。查一个java.nio.file.Files.readString的异常说明要点进五六层页面还得在浏览器里开翻译插件既慢也不方便同事复用。所以标题里的“Java17 中文文档 HTML 版本”指的并不是某个开箱即用的官方中文发布包而是一套把官方 JavaDoc 页面本地化、离线化、且仍然保持 HTML 网页可检索形态的做法。它解决三个问题中文阅读、离线访问、页面间可跳转检索。适合两类人一类是想在公司内网搭 Java 17 API 文档站的运维或架构工程师另一类是希望边写代码边查证 Java 17 新特性的开发人员。这个工作看起来只是“翻译一堆网页”实际上牵涉 HTML 字符编码、JavaDoc 生成参数、索引文件的离线检索机制以及浏览器打开方式的选型。下文把这条路一次性说透照着做能拿到一份可发给同事的离线版中文 HTML 文档。2. Java17 官方 HTML 文档的结构离线可搜的 JavaDoc 产物要本地化一份文档先要摸清它的目录结构和渲染机制。Java 17 的官方文档不是单一 PDF而是一个多模块页面树api/java.base/java/lang/String.html、api/java.base/java/util/List.html这类路径对应的是java.base模块下的类页面index-files目录存放所有索引页search.js、type-search-index.js、member-search-index.js、tag-search-index.js这组文件则支撑页面顶部搜索框的离线检索。HTML 版本之所以比 Markdown 或 PDF 更适合做中文文档是因为 JavaDoc 生成器已经把所有类、方法、字段的跳转关系编译成了静态链接翻译时只需要替换页面正文文字链接结构可以原样保留。这意味着你可以在不重写站点架构的前提下把一份官方英文 HTML 文档批处理成中文 HTML 文档。2.1 从 JDK 17 发布渠道提取离线文档两条路径常见做法有两种取决于你手上有什么。第一种是从官方发布渠道获取与当前 JDK 版本匹配的离线文档归档解压后得到完整的英文 HTML 页面# 假设你已经把文档归档放到 /opt/java17-docs/ mkdir -p /data/workspace/zh-jdk17-docs cd /data/workspace/zh-jdk17-docs unzip /opt/java17-docs/jdk-17.0.12_doc-all.zip find . -maxdepth 2 -type d | head -20这里doc-all.zip解压出来通常包含api、specs、legal等目录其中api就是后续要本地化的主战场。注意归档版本要和线上 JDK 的小版本尽量对齐比如生产环境是 17.0.12就下载对应版本的文档避免接口签名差异造成误导。第二种路径是直接从 JDK 安装目录带出的src.zip自己生成 HTML 文档。这种方式的好处是文档与线上 JDK 完全同源缺点是需要先处理模块源码路径。适合那些连文档归档都不方便获取、但已经有完整 JDK 的环境具体命令见下一节。2.2 用 javadoc 自己构建一份 HTML 版本如果你已经安装了 java17并且能在命令行跑通javadoc可以跳过下载步骤直接对 JDK 附带的源码生成 HTML 文档。先把src.zip解压到工作目录再做模块化构建mkdir -p /data/jdk17-src cd /data/jdk17-src unzip -q $JAVA_HOME/lib/src.zip -d src cd src javadoc \ --release 17 \ -d /data/workspace/zh-jdk17-docs/api \ -locale zh_CN \ -encoding UTF-8 \ -charset UTF-8 \ -docencoding UTF-8 \ -Xdoclint:none \ --module-source-path . \ --module java.base,java.sql,java.naming,java.desktop,java.net.http这条命令里几个参数的含义--release 17表示按 Java 17 的 API 表面生成文档不会因为本地 JDK 是更高版本而带出新 API-locale zh_CN让生成器把“Overview”“Package”这类框架文字渲染成中文但类注释和方法说明仍是源码里的英文原文-encoding、-charset、-docencoding三个参数统一输入和输出编码缺一个都可能在后续批处理时出现中文乱码-Xdoclint:none关闭文档规范检查避免因为源码注释里的 HTML 标签不规范导致整个构建中断。生成完毕后api目录下会出现index.html、overview-tree.html、constant-values.html、serialized-form.html等标准文件搜索框依赖的search.js也会一并生成。这一步验证通过说明整套 HTML 版本可以在本地复现后续中文替换只是内容层操作不会破坏结构。2.3 search.js 与索引文件HTML 版本自带的离线检索Java 17 的 JavaDoc 页面顶部搜索框并不是请求外部搜索引擎而是读取本地生成的索引文件。type-search-index.js存了所有类名和接口名member-search-index.js存了所有字段和方法名tag-search-index.js存了since、deprecated这类标签信息搜索时由search.js在前端做模糊匹配。这带来一个对本地中文文档很关键的限制索引文件里的英文条目必须保留不能为了“全中文”把索引里的类名也翻译掉。正确做法是只翻译页面展示文案索引保持英文原样这样中文读者搜Files或readString仍然能命中。同理index-files目录下的按字母索引页可以保留英文标题但可以在标题旁补充中文模块名说明。理解了这套结构接下来就能动本地化改造了。不要试图重新发明文档站JavaDoc 生成器已经替你把最难的部分做完了。3. 把英文 HTML 文档本地化成中文的五步做法拿到干净的官方 HTML 版本之后本地化不是逐页手工翻译而是按文件类型分层处理。JavaDoc 页面里的文案分三类框架栏文字“Overview”“Package”“Class”、注释正文div.block里的说明、签名部分member-signature里的方法名和参数。三类文案的替换策略完全不同下面的步骤按执行顺序展开。3.1 先统一编码与 lang 属性html 标签层面的预处理官方英文文档的 HTML 标签里声明的是langen部分老资源还是单字节编码。如果不先统一成 UTF-8 并把语言标记改成zh-CN后面替换中文时浏览器会按错误编码解析导致乱码而且无障碍阅读器和搜索引擎都会把文档识别成英文。cd /data/workspace/zh-jdk17-docs/api # 把所有 HTML 文件统一转为 UTF-8 无 BOM 格式 find . -name *.html -type f -exec sed -i s/html langen/html langzh-CN/g {} \; # 检查是否还有残留的 langen grep -rl langen . | head -5这里用sed -i直接原地替换配合find -exec遍历整个目录树。如果原始文件是 ISO-8859-1 编码需要先用iconv -f ISO-8859-1 -t UTF-8做转换再执行替换否则高字节字符会被截断。替换完成后打开任意页面查看源码确认html langzh-CN和meta charsetUTF-8同时存在这一步是所有后续替换的地基。3.2 复用中文术语表替换 API 文案JavaDoc 的注释正文有固定结构英文方法说明通常以Returns、Throws、Parameters、Specified by开头。这些结构词可以直接映射成中文术语用正则做批量替换不需要人工上下文判断。cd /data/workspace/zh-jdk17-docs/api # 按优先级替换先替换长短语再替换单词避免子串误伤 sed -i \ -e s/Specified by:/实现自/g \ -e s/Overrides:/覆盖自/g \ -e s/Parameters:/参数/g \ -e s/Returns:/返回/g \ -e s/Throws:/抛出/g \ -e s/Since:/始于版本/g \ -e s/See Also:/另见/g \ -e s/Default Value:/默认值/g \ $(find . -name *.html)注意替换顺序Returns:必须先于任何更短的模式执行否则如果某个类名里恰好包含这个单词会被误替换。翻译正文里的完整句子时一个更稳妥的做法是用 Python 解析出div.block内容做对照翻译而不是全局替换。因为全局sed可能污染方法名和类名比如java.lang.ProcessHandle里的Handle不能翻成“句柄”。术语表方式适合结构性短语完整句子建议走机器翻译后再人工校对把结果按文件路径回写到对应 HTML 里。3.3 不要用“html 转 md”再转回 HTML 的偷懒方案有些团队为了省事先写脚本把 HTML 转成 Markdown 翻译完再转回 HTML这种做法在这里会毁掉整份文档。JavaDoc 页面里的a href跳转、code内联代码、pre签名块和id锚点在 Markdown 往返转换后会出现三类问题相对链接的层级关系丢失、member-search-index.js里的锚点与页面id对不上、pre里等宽字体样式被压平。如果确实需要批量提取正文去翻译正确做法是只提取文本不进原文。用 Python 的 HTMLParser 把div.block内的纯文本抽出来翻译译完再按原路径写回对应节点结构标签一个都不动。搜索索引文件search.js和各类*-search-index.js完全不要碰它们是英文原版结构的一部分。3.4 示例代码与说明文字同步翻译HTML 页面里除了 API 注释还有example相关段落和使用示例代码块。代码块内的方法名、变量名要保持英文原名但注释要翻译。这里可以用一个简单的 Python 脚本按文件批量处理import re from pathlib import Path def translate_pre_comments(text: str) - str: 把 pre 代码块里的 // 英文注释替换成中文行号与缩进不变 def repl(match): block match.group(0) lines [] for line in block.splitlines(): if line.strip().startswith(//): # 这里接你的术语对照表示例化实现 line re.sub(r//\s*(.*), lambda m: f// {TERMS.get(m.group(1), m.group(1))}, line) lines.append(line) return \n.join(lines) return re.sub(rpre.*?/pre, repl, text, flagsre.S) for html_file in Path(/data/workspace/zh-jdk17-docs/api).rglob(*.html): content html_file.read_text(encodingutf-8) content translate_pre_comments(content) html_file.write_text(content, encodingutf-8)这段脚本用正则匹配pre块逐行处理//开头的注释。TERMS字典可以维护成业务词汇表比如creates a new file - 创建新文件。逻辑重点在于只动注释行不动代码本身写成文件回写而不是打印预览是为了便于 git diff 查看每一步改动。4. 生成“Java17中文文档”时的必调参数与排错本地化过程中真正耗时间的不是翻译而是各种环境不一致导致的构建和预览问题。下面按参数、预览方式、高频报错三条线展开每一条都是实际改动时容易踩的坑。4.1 javadoc 命令里 4 个影响中文输出的参数自定义构建时下面的参数表建议直接保存成构建脚本的固定配置参数作用不设置的后果-locale zh_CN生成器自带按钮、标签显示为中文框架部分仍是英文-encoding UTF-8指定源码读取编码源码注释里的中文读取乱码-charset UTF-8指定生成页面字符集浏览器自动识别成 GBK 或 ISO-8859-1-docencoding UTF-8指定最终 HTML 文件编码HTTP 响应头与文件实际编码不一致其中最容易忽略的是-locale zh_CN与-docencoding UTF-8的配合。前者只影响生成器输出的 UI 文案后者影响所有页面文件的落盘编码两个都设了中文才能稳定显示。如果是在 Windows 环境执行路径含有空格时整个命令要在 PowerShell 里用--%或把路径用双引号包裹避免 javadoc 把路径拆分。4.2 本地预览必须走 HTTPfile:// 会触发搜索失效文档本地化完成后第一步验证应该是启动本地 HTTP 服务而不是双击index.html。原因在于search.js在 Java 17 的 JavaDoc 里使用fetch加载索引文件而fetch在file://协议下会被浏览器拦截表现为搜索框输入后无任何结果。cd /data/workspace/zh-jdk17-docs python3 -m http.server 8080 --bind 0.0.0.0启动后访问http://localhost:8080/api/index.html。浏览器地址必须是 HTTP 协议且页面上能搜到Files、List等类名。这个 Python 命令把当前目录作为站点根目录--bind 0.0.0.0是让同网段同事也能访问仅本机预览时可以去掉。4.3 高频报错乱码、路径带空格、doclint 中断乱码的排查顺序是先看 HTMLmeta声明再看 HTTP 响应头最后看源文件字节。三者必须一致都是 UTF-8。很多场景下源码注释里混入了 GBK 编码的中文字符-encoding UTF-8会直接报“编码 UTF-8 的不可映射字符”这时用iconv -f GBK -t UTF-8单独转码对应源文件而不是改全局参数。路径带空格是 Windows 下的常见错误javadoc会把C:\Program Files\...按空格拆成两个参数报javadoc: error - Illegal package name。解决方法是把整个输出的-d路径和模块路径都放进引号或者在目录名里避免空格。doclint 中断则是最隐蔽的某些第三方源码注释里的{link}标签引用了不存在的类javadoc默认会报错退出。构建工具链里加上-Xdoclint:none只输出文档不校验注释规范即可绕开这种与本地化无关的构建碎片问题。4.4 用一张表记住常见问题与排查命令问题现象可能原因排查命令搜索框无结果用 file:// 打开改用python3 -m http.server预览页面中文变问号编码参数未统一file -i index.html查看字符集-encoding报错源文件混入 GBKiconv -l | grep GBK确认可用编码后转换生成过程中断doclint 校验失败检查输出里的error:行加-Xdoclint:none方法跳转 404链接层级被改写find . -name *.html | wc -l对比替换前后文件数这一轮排错做完文档基本能在本机稳定访问。接下来是把这份成果接入开发环境的日常流程让它真正替代浏览器查英文文档的习惯。5. 把中文 HTML 文档接进 IDE 与批量校验的技巧文档做得再好如果不接入 IDE 的 JavaDoc 查看面板使用频率会大大降低。以 IntelliJ IDEA 为例在Project Structure的 SDK 配置里选中 JDK 17 后把Documentation Paths指向本地api/index.html即可。之后鼠标悬停在Files.readString上弹出的 Javadoc 面板显示的就是本地中文版本无需联网。这一招也适用于 Eclipse配置位置在Window - Preferences - Java - Installed JREs里选中 JDK 后点击Javadoc按钮修改。接入 IDE 后还要验证翻译是否漏掉了一大片。用 ripgrep 统计残留英文结构词比人工抽查覆盖率更可靠cd /data/workspace/zh-jdk17-docs/api # 统计还有多少页面残留英文 Returns: 结构词 rg -l Returns: --glob *.html | wc -l # 统计包含中文的页面数量 rg -l [\x{4e00}-\x{9fff}] --glob *.html | wc -l两条命令的差值就是还没覆盖的页面。如果差值很大优先检查serialized-form.html和constant-values.html这类非 API 页面容易被批处理脚本漏掉。更细的校验是检查所有页面里是否有互斥的langen和langzh-CN并存说明替换脚本没有跑遍全部文件。最后做一次链接完整性检查确保没有因为批量替换把相对路径写坏。用 Python 脚本遍历所有 HTML 页面收集href断言目标文件存在import re from pathlib import Path from urllib.parse import urlparse, unquote api Path(/data/workspace/zh-jdk17-docs/api) broken [] for html in api.rglob(*.html): for href in re.findall(rhref([^]), html.read_text(encodingutf-8)): target unquote(urlparse(href).path) if target.startswith(http) or target.startswith(#) or :// in target: continue if not (api / target).exists(): broken.append(f{html.relative_to(api)} - {target}) print(fbroken links: {len(broken)}) for item in broken[:20]: print(item)这段脚本跳过外链和页面内锚点只检查本地相对链接。跑完输出为空说明整套 HTML 文档的内部跳转完好。注意脚本里特意排除了://的绝对地址因为在离线文档环境里出现绝对域名链接就意味着页面会尝试请求外网资源这也是本地化后最容易被忽略的一处残留。本文还有配套的精品资源点击获取 
