Come creare JavaDocs multilingue?

Question

Esiste JavaDoc di una normale API Java con un'edizione inglese e un'edizione cinese, ma sembra richiedere un codice sorgente separato per ogni edizione. C'è un modo più conveniente per fare questo?

Answer 1

No, non c'è praticamente alcun modo di farlo.

L'unica soluzione che viene in mente si applica alle pagine HTML generate: è possibile circondare JavaDocs in elementi di blocco che alternano le lingue tramite CSS. Considerate:

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

modificare Successivamente il CSS dei JavaDocs in modo che l'utente può passare da una lingua, ad es .:

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

Answer 2

La risposta breve è no. I commenti e gli strumenti javadoc esistenti non supportano questo.

Non credo sarebbe una buona idea aggiungere il supporto per incorporare più traduzioni di commenti javadoc nel codice sorgente. Non sarebbe una soluzione scalabile:

• Man mano che ogni nuova traduzione viene aggiunta, i file del codice sorgente diventano più grandi.
• Le descrizioni multi-lingue sarebbero molto difficili da gestire.

Considera che sono uno sviluppatore API che non legge/scrive cinese. Quando aggiorno i javadoc in inglese, come faccio a segnalare che i commenti di javadoc cinesi devono essere aggiornati? Cosa facciamo per il problema che un numero potenzialmente elevato di traduttori deve aggiornare i file del codice sorgente e potrebbe accidentalmente introdurre regressioni nel codice reale? In che modo il gestore del rilascio garantisce che tutte le traduzioni vengano eseguite prima della versione "gold"?

Penso che una soluzione migliore (ipotetica) sia quella di avere uno strumento javadoc modificato che estrae i commenti di javadoc in un database di versione. Quindi scrivi uno strumento che noti quando un commento javadoc primario (ad esempio inglese) cambia nei database e richiede agli scrittori/traduttori tecnici di apportare le modifiche corrispondenti nelle traduzioni cinese, olandese, ecc. Di javadoc.