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)
