[
https://issues.apache.org/jira/browse/RATIS-2424?page=com.atlassian.jira.plugin.system.issuetabpanels:all-tabpanel
]
Xinyu Tan updated RATIS-2424:
-----------------------------
Description:
*Background*
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
was:
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
> 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
> Priority: Major
> Time Spent: 10m
> Remaining Estimate: 0h
>
> *Background*
> 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)
