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?
Add a comment
|
3 Answers
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; }
answered Sep 26, 2009 at 23:49
Paul Lammertsma
38.4k17 gold badges139 silver badges190 bronze badges
5 Comments
freddiefujiwara
Very good idea Thanks a lot! How to add Javascripts in JavaDoc?
Paul Lammertsma
I see you already received an answer to your question here: stackoverflow.com/questions/1483141
lamostreta
First thanks for the nice solution. I tried it but couldn't make it work: I tried display result was unsuccessfull. Then I tried these codes: codetidy.com/7825 but still no good. Do you have any reccommendation?
Paul Lammertsma
@lamostreta Are you sure your CSS is being referenced?
lamostreta
Actually I edited the css that is created by javadoc comment. Its name is javadoc.css. For example when I change the font color it works, but other commands don't work.
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.
Comments
Maybe too late for you, but others may find this useful:
You can use this github tool I wrote
https://github.com/omarazrat/javadoc_taglets
It provides the tag @lang, which produces the same HTML code explained by Paul Lammertsma, just using a more natural tag inside code
{@lang "en"
Greetings from Alexandria}
{@lang "ar" تحياتي من الإسكندرية}
{@lang "ja" アレクサンドリアからのご挨拶 }
And the repo is self-documented, so you can see the action of a proper stylesheet on the generated HTM DIV instructions.
