You are viewing a plain text version of this content. The canonical link for it is here.
Posted to issues@ratis.apache.org by "Xinyu Tan (Jira)" <ji...@apache.org> on 2026/03/08 11:37:00 UTC
[jira] [Created] (RATIS-2424) Fix javadoc locale configuration for JDK 8 compatibility
Xinyu Tan created RATIS-2424:
--------------------------------
Summary: Fix javadoc locale configuration for JDK 8 compatibility
Key: RATIS-2424
URL: https://issues.apache.org/jira/browse/RATIS-2424
Project: Ratis
Issue Type: Improvement
Reporter: Xinyu Tan
Assignee: Xinyu Tan
PR #1365 added `-locale en_US` to the maven-javadoc-plugin configuration to ensure English javadoc
generation. However, this approach fails on JDK 8 with the following error:
javadoc: error - option -locale must be first on the command line.
Command line was: ... -Xmaxwarns 10000 -Xdoclint:-missing -locale en_US @options @packages
JDK 8's javadoc requires the `-locale` option to be the first argument on the command line, but
maven-javadoc-plugin cannot guarantee this parameter order.
The solution is to use JVM system properties instead:
```xml
<additionalJOption>-J-Duser.language=en</additionalJOption>
<additionalJOption>-J-Duser.country=US</additionalJOption>
This approach sets the locale at JVM startup time, before javadoc runs, ensuring compatibility with both
JDK 8 and JDK 11+.
Verification Results
Environment: JDK 11 + Chinese locale
JVM Params: With -J-Duser.language=en -J-Duser.country=US
Result: ✅ English ("Method Summary")
────────────────────────────────────────
Environment: JDK 11 + Chinese locale
JVM Params: Without JVM params
Result: ❌ Chinese ("方法概要")
────────────────────────────────────────
Environment: JDK 8 + Chinese locale
JVM Params: With -J-Duser.language=en -J-Duser.country=US
Result: ✅ English ("Method Summary")
Conclusion
The JVM parameter approach (-J-Duser.language=en and -J-Duser.country=US) is effective:
- Under Chinese locale environment (LANG=zh_CN.UTF-8)
- On both JDK 8 and JDK 11
- The generated javadoc is always in English, regardless of the build system's locale settings
--
This message was sent by Atlassian Jira
(v8.20.10#820010)