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)