JavaDoc i18nにする方法
T2のJavaDocのために、幾つかJavaDocをi18nにする方法を試してみましたのでここに書いてみる。
何をやろうとしているかというと、JavaDocを英語、日本語両方で出力したいという割と単純かつよくありそうな要望です。
localized docletを使う方法
最初に試したのがこれ。Doclet拡張ですね。
簡単に言うと、日本語部分には{@.ja }、英語部分には{@.en }で括る。
記事としてはこれが最初に読んだやつです。
プロダクトとしてはid:skimuraさんが出しているのでこちらを利用しました。ありがとうございます。
メリット
比較的簡単に使えます。私はmaven2から使っていたので、maven-javadocプラグインに以下のように設定して、
mvn javadoc:javadocするだけで使えます。
<plugin> <artifactId>maven-javadoc-plugin</artifactId> <configuration> <source>1.6</source> <encoding>UTF-8</encoding> <docencoding>UTF-8</docencoding> <charset>UTF-8</charset> <locale>ja_JP</locale> <links> <link>http://java.sun.com/javase/6/docs/api/</link> </links> <taglets> <taglet> <tagletClass>jp.dodododo.javadoc.doclet.localization.LanguageTaglet</tagletClass> <tagletArtifact> <groupId>jp.dodododo.localization-doclet</groupId> <artifactId>localization-doclet</artifactId> <version>0.1.0</version> </tagletArtifact> </taglet> </taglets> </configuration> </plugin>
デメリット
1行以上の長い文章がちゃんと処理されないです。多分Docletのそもそものつくりが悪いんじゃないかと予想。
なので、1行ずつ{@.jaとかで括る必要が出てきます。割とがっつり書きたい・書こうと思ってる人にはちょっと不向き。
FreeMarkerを使う方法
次にやってみたのが、FreeMarker(FMPP)+Antを使って
というもの。
サイトは以下を参考にしました。ありがとうございます。
しかしながら、残念ですが上のやつだけでは現在はダメのようでした。どうやらJava5からのアノテーションまわりのJavaDocの処理が
きちんと対処されておらず、ClassCast例外でおちまくって幾つかのhtmlが出力されないという事態に陥りました。
バグとしてはまだUnfixedっぽい(困ってる人多数)・・・以下を参照。
というわけでこの対処方法としては、使ってるアノテーションのクラスパスを全部javadocタスクに通してやる必要があります。
というわけでbuild.xmlがこんな感じになりました。
<?xml version="1.0" encoding="UTF-8" standalone="no"?> <project basedir="." default="javadoc" name="t2"> <property name="fmpp.lib" value="./javadoc-lib/fmpp.jar" /> <taskdef name="fmpp" classname="fmpp.tools.AntTask" classpath="${fmpp.lib}" /> <path id="javadoc.path"> <pathelement location="target/classes" /> <pathelement location="target/test-classes" /> <fileset dir="javadoc-lib"> <include name="*.jar" /> </fileset> <fileset dir="lib"> <include name="*.jar" /> </fileset> <fileset dir="lib/optional"> <include name="*.jar" /> </fileset> <fileset dir="webapp/WEB-INF/lib"> <include name="*.jar" /> </fileset> </path> <target name="javadoc" description="Generate javadoc."> <mkdir dir="target/logs"/> <macrodef name="javadoc-i18n"> <attribute name="locale" /> <sequential> <mkdir dir="target/javadocsrc-@{locale}" /> <fmpp sourceroot="src" outputroot="target/javadocsrc-@{locale}" data="locale:@{locale}" logfile="target/logs/log-@{locale}.fmpp"> <exclude name="META-INF/t2.tld" /> </fmpp> <javadoc source="1.6" author="true" sourcepath="target/javadocsrc-@{locale}" destdir="target/javadoc-@{locale}" windowtitle="T2 framework" Locale="@{locale}" encoding="UTF-8" package="org.t2framework.t2.*" charset="UTF-8"> <classpath refid="javadoc.path"> </classpath> <link href="http://java.sun.com/javase/6/docs/api" /> <link href="http://java.sun.com/products/servlet/2.5/docs/servlet-2_5-mr2/index.html" /> </javadoc> </sequential> </macrodef> <javadoc-i18n locale="ja" /> <javadoc-i18n locale="en" /> </target> </project>
これで、ソースに以下のようなJavaDocを書いて、Antすると見事日本語JavaDocと英語JavaDocが出来上がります。
/** * <#if locale="en"> * <p> * ActionUtil handles T2-specific things.This utility class is absolutely * internal class. * </p> * <#else> * <p> * ActionUtilはT2独自の処理を行います.このユーティリティクラスは、T2の内部だけで利用されるクラスです. * </p> * </#if> * * @author shot */
メリット
メリットはきちんとがっつりJavaDoc書いても大丈夫なところですね。特に量書く場合はこちらの方が良いでしょう。
T2ではこちらを採用することにしました。
