How to create multi-language JavaDocs?

Question

There is JavaDoc of a normal Java API with an English edition and a Chinese edition, but it seems to require having separate source code for each edition. Is there any more convenient way to do this?

Answer 1

No, there is essentially no way of doing this.

The only work-around that comes to mind applies to the generated HTML pages: you could surround the JavaDocs in block elements that toggle between languages using CSS. Consider:

/**
 * <div class="en">Documentation in English</div>
 * <div class="nl">Documentatie in Nederlands</div>
 */
public void myFunction() {}

Subsequently edit the CSS of the JavaDocs so that the user can switch languages, e.g.:

div.en { display:none; }
div.nl { display:block; }

Answer 2

The short answer is no. The existing javadoc comments and tools don't support this.

I don't think it would be a good idea to add support for embedding multiple translations of javadoc comments in the source code. It would not be a scalable solution:

• As each new translation is added the source code files get bigger.
• The multi-lingual descriptions would be very difficult to manage.

Consider that I'm an API developer who doesn't read / write Chinese. When I update the English javadocs, how do I flag that the Chinese javadoc comments need to be updated? What do we do about the problem that a potentially large number of translators need to update the source code files and could accidentally introduce regressions into the actual code? How does the release manager ensure that all translations are done before the "gold" release?

I think that a better (hypothetical) solution is to have a modified javadoc tool that extracts the javadoc comments into a version database. Then write a tool that that notices when a primary (e.g. English) javadoc comment changes in the databases, and prompts the technical writers / translators to make the corresponding changes in the Chinese, Dutch, etc translations of the javadoc.