All,
I've been looking into how javadoc chooses the locale for the generated
documentation so that release builds are more reproducible.
A problem has been reported against Java 11-12, with Java 8 claimed to
be working and a fix claimed in Java 15, where the -locale switch for
the javadoc tool would use the LANG environment variable in preference
to -locale which was very surprising.
https://bugs.openjdk.org/browse/JDK-8222793?focusedId=14315060&page=com.atlassian.jira.plugin.system.issuetabpanels%3Acomment-tabpanel
I'm performing all of my testing using Java 17 and later, which should
be well past the "fixed version".
First, using LANG=en_US.utf8, modifying the Tomcat build to include
locale="de" in all calls to <javadoc> and then invoking:
$ ant javadoc
With Java 23, this results in javadoc output whose interface is all in
the German language. Note that the descriptions of all of the classes,
methods, etc. are in English because that's how they are in the Java
source files. This is exactly the behavior I would expect.
With Java 21, this results in javadoc output whose interface is all in
the German language. Note that the descriptions of all of the classes,
methods, etc. are in English because that's how they are in the Java
source files.
With Java 17, this results in javadoc output whose interface is in
English. The documents contain <html lang="de"> which leads me to
believe that Java 17 still has some vestiges of this bug present. I
think perhaps it's because Java 17 does not include a German language
bundle for javadoc? By specifying LANG=de and running Javadoc, I still
do not get German text as expected.
I can't test with Java 8 because the current build, even when asked not
to ignore the Java version, fails to build for javadoc for other reasons.
There is a workaround mentioned in the bug report which is to not only
specify -locale but also -Duser.language and -Duser.country when
invoking javadoc.
Below is a summary of all of the combinations of things I tried to get
things working as expected (which is that a small number of properties
specified in build.properties.default will control the javadoc
language). The results are the same for all combinations whether adding
the system property "workaround" from above.
I have added locale="${javadoc.locale}" to all <javadoc> invocations in
build.xml in main but never back-ported them. My commit
b770297e6cd96220e253079aee26fa2ff5b85aeb included the workaround
mentioned in this bug report, but my testing indicates that the
workaround is no longer necessary in the Java versions that we use for
releases.
I will therefore revert b770297e6cd96220e253079aee26fa2ff5b85aeb and
back-port 3d58c3ac70beb21588b120d21ff5c075801ca31e.
I'm a little puzzled by the fact that Japanese never generated ANY
Japanese text, while German seemed to work some of the time.
Details:
====================
env.LANG=en
Java 17.0.14
javadoc.locale=en
javadoc.language=en
javadoc.country=US
<html lang="en">
<title>Overview (Apache Tomcat 10.1.41-dev API Documentation)</title>
====================
env.LANG=en
Java 17.0.14
javadoc.locale=de
javadoc.language=de
javadoc.country=US
<html lang="de">
<title>Overview (Apache Tomcat 10.1.41-dev API Documentation)</title>
====================
env.LANG=en
Java 17.0.14
javadoc.locale=jp
javadoc.language=jp
javadoc.country=US
<html lang="jp">
<title>Overview (Apache Tomcat 10.1.41-dev API Documentation)</title>
====================
env.LANG=de
Java 17.0.14
javadoc.locale=en
javadoc.language=en
javadoc.country=US
<html lang="en">
<title>Overview (Apache Tomcat 10.1.41-dev API Documentation)</title>
====================
env.LANG=de
Java 17.0.14
javadoc.locale=de
javadoc.language=de
javadoc.country=US
<html lang="de">
<title>Overview (Apache Tomcat 10.1.41-dev API Documentation)</title>
====================
env.LANG=de
Java 17.0.14
javadoc.locale=jp
javadoc.language=jp
javadoc.country=US
<html lang="jp">
<title>Overview (Apache Tomcat 10.1.41-dev API Documentation)</title>
====================
env.LANG=jp
Java 17.0.14
javadoc.locale=en
javadoc.language=en
javadoc.country=US
<html lang="en">
<title>Overview (Apache Tomcat 10.1.41-dev API Documentation)</title>
====================
env.LANG=jp
Java 17.0.14
javadoc.locale=de
javadoc.language=de
javadoc.country=US
<html lang="de">
<title>Overview (Apache Tomcat 10.1.41-dev API Documentation)</title>
====================
env.LANG=jp
Java 17.0.14
javadoc.locale=jp
javadoc.language=jp
javadoc.country=US
<html lang="jp">
<title>Overview (Apache Tomcat 10.1.41-dev API Documentation)</title>
====================
env.LANG=en
Java 21.0.5
javadoc.locale=en
javadoc.language=en
javadoc.country=US
<html lang="en">
<title>Overview (Apache Tomcat 10.1.41-dev API Documentation)</title>
====================
env.LANG=en
Java 21.0.5
javadoc.locale=de
javadoc.language=de
javadoc.country=US
<html lang="de">
<title>Überblick (Apache Tomcat 10.1.41-dev API Documentation)</title>
====================
env.LANG=en
Java 21.0.5
javadoc.locale=jp
javadoc.language=jp
javadoc.country=US
<html lang="jp">
<title>Overview (Apache Tomcat 10.1.41-dev API Documentation)</title>
====================
env.LANG=de
Java 21.0.5
javadoc.locale=en
javadoc.language=en
javadoc.country=US
<html lang="en">
<title>Overview (Apache Tomcat 10.1.41-dev API Documentation)</title>
====================
env.LANG=de
Java 21.0.5
javadoc.locale=de
javadoc.language=de
javadoc.country=US
<html lang="de">
<title>Überblick (Apache Tomcat 10.1.41-dev API Documentation)</title>
====================
env.LANG=de
Java 21.0.5
javadoc.locale=jp
javadoc.language=jp
javadoc.country=US
<html lang="jp">
<title>Overview (Apache Tomcat 10.1.41-dev API Documentation)</title>
====================
env.LANG=jp
Java 21.0.5
javadoc.locale=en
javadoc.language=en
javadoc.country=US
<html lang="en">
<title>Overview (Apache Tomcat 10.1.41-dev API Documentation)</title>
====================
env.LANG=jp
Java 21.0.5
javadoc.locale=de
javadoc.language=de
javadoc.country=US
<html lang="de">
<title>Überblick (Apache Tomcat 10.1.41-dev API Documentation)</title>
====================
env.LANG=jp
Java 21.0.5
javadoc.locale=jp
javadoc.language=jp
javadoc.country=US
<html lang="jp">
<title>Overview (Apache Tomcat 10.1.41-dev API Documentation)</title>
====================
env.LANG=en
Java 23.0.2
javadoc.locale=en
javadoc.language=en
javadoc.country=US
<html lang="en">
<title>Overview (Apache Tomcat 10.1.41-dev API Documentation)</title>
====================
env.LANG=en
Java 23.0.2
javadoc.locale=de
javadoc.language=de
javadoc.country=US
<html lang="de">
<title>Überblick (Apache Tomcat 10.1.41-dev API Documentation)</title>
====================
env.LANG=en
Java 23.0.2
javadoc.locale=jp
javadoc.language=jp
javadoc.country=US
<html lang="jp">
<title>Overview (Apache Tomcat 10.1.41-dev API Documentation)</title>
====================
env.LANG=de
Java 23.0.2
javadoc.locale=en
javadoc.language=en
javadoc.country=US
<html lang="en">
<title>Overview (Apache Tomcat 10.1.41-dev API Documentation)</title>
====================
env.LANG=de
Java 23.0.2
javadoc.locale=de
javadoc.language=de
javadoc.country=US
<html lang="de">
<title>Überblick (Apache Tomcat 10.1.41-dev API Documentation)</title>
====================
env.LANG=de
Java 23.0.2
javadoc.locale=jp
javadoc.language=jp
javadoc.country=US
<html lang="jp">
<title>Overview (Apache Tomcat 10.1.41-dev API Documentation)</title>
====================
env.LANG=jp
Java 23.0.2
javadoc.locale=en
javadoc.language=en
javadoc.country=US
<html lang="en">
<title>Overview (Apache Tomcat 10.1.41-dev API Documentation)</title>
====================
env.LANG=jp
Java 23.0.2
javadoc.locale=de
javadoc.language=de
javadoc.country=US
<html lang="de">
<title>Überblick (Apache Tomcat 10.1.41-dev API Documentation)</title>
====================
env.LANG=jp
Java 23.0.2
javadoc.locale=jp
javadoc.language=jp
javadoc.country=US
<html lang="jp">
<title>Overview (Apache Tomcat 10.1.41-dev API Documentation)</title>
-chris
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscr...@tomcat.apache.org
For additional commands, e-mail: dev-h...@tomcat.apache.org
