Uploaded image for project: 'JDK'
  1. JDK
  2. JDK-8222793

Javadoc tool ignores "-locale" param and uses default locale for all messages and texts

    Details

    • Subcomponent:
    • Resolved In Build:
      b09
    • CPU:
      generic
    • OS:
      generic

      Description

      Javadocs has the "-locale" parameter that allows to give the locale for generated javadocs, e.g. for English projects like Apache Lucene, the texts about methods, classes, titles should really be in English. To achieve this, you can pass "-locale en_US".

      The problem: Javadocs ignores the param in Java 11 and Java 12 - but works correctly in Java 8. Giving the parameter has exactly one effect: it changes the language attribute of the element (and date/times in comments seem to be correct). If the default locale is Japanese (as on a Lucene committer's test system), all remaining text is japanese:

      System setup:

      $ /usr/java/jdk-11.0.3/bin/jshell
      jshell> Locale.getDefault()
      $1 ==> ja_JP

      Without locale option:

      ```$ /usr/java/jdk-11.0.3/bin/javadoc --source-path src/java -d docs/ -package "com.example"
      $ cat docs/index.html
      <html lang="ja">
      <head>
      <!-- Generated by javadoc (11.0.3) on Sun Apr 21 22:13:06 JST 2019 -->
      <title>生成されたドキュメント(タイトルなし)</title>
      ...```
      With locale option:

      ```$ /usr/java/jdk-11.0.3/bin/javadoc -locale en_US --source-path src/java -d docs/ -package "com.example"
      $ cat docs/help-doc.html
      <html lang="en">
      <head>
      <!-- Generated by javadoc (11.0.3) on Sun Apr 21 22:13:34 JST 2019 -->
      <title>生成されたドキュメント(タイトルなし)</title>
      ...```

      The only workaround is to give the locale as a system property with "-J" param: And when I give the locale via sysprops, lang is "en" and the generated texts are English:

      ```$ /usr/java/jdk-11.0.3/bin/javadoc --source-path src/java -d docs/ -package "com.example" -J-Duser.language=en -J-Duser.country=US
      $ cat docs/index.html
      <html lang="en">
      <head>
      <!-- Generated by javadoc (11.0.3) on Sun Apr 21 22:21:14 JST 2019 -->
      <title>Generated Documentation (Untitled)</title>
      ...```

      In Apache Lucene we now pass both things (-locale) and sysprops. But this issue may affect many projects.

      Interestingly, with German default Locale it does not happen, but this could be related to the fact that there are no German messages shipped with JDK.

      Java 8 works fine.

        Attachments

          Issue Links

            Activity

              People

              • Assignee:
                jjg Jonathan Gibbons
                Reporter:
                uschindler Uwe Schindler
              • Votes:
                0 Vote for this issue
                Watchers:
                7 Start watching this issue

                Dates

                • Created:
                  Updated:
                  Resolved: