javadoc을 localization하기 by 오리대마왕

javadoc은 localization을 지원하지 않는다. 단지 source의 javadoc tag의 내용을 읽어서 곧바로 html로 만든다. 그럼 API 문서를 여러 언어로 제공해야 할 경우엔 어떻게 해야 할까? 그냥 모든 국가의 언어를 모조리 source에 심어넣어야 할까?

다행히 http://sourceforge.net/projects/l10ndoclet/ 는 이런 불행한 사태에 대한 해결책을 제시해 준다. readme에서 볼 수 있듯이, 이 custom doclet을 사용하는 과정은 다음과 같다.
  • preprocess 단계: 소스코드의 javadoc tag의 내용을 뽑아 xml 파일을 만들어낸다. 이 xml 파일은 소스코드 파일 별로 생긴다.
  • 번역 단계: 생성된 커멘트 xml 파일을 다른 언어로 번역한다.
  • postprocess 단계: 번역 단계에서 만든 xml 파일을 이용해 javadoc을 만든다.
그런데 실제 생성해 보면 사소한 아쉬움이 있다. html의 charset이 누락되어 일부 브라우저에선 한글이 깨져 보인다. javadoc의 standard doclet의 flag인 -charset 을 이용하면 이 문제를 해결할 수 있는데, 이상하게 이 l10ndoclet을 쓰면 이 flag가 invalid하다고 나온다.

그래서 코드를 다음과 같이 살짝 수정했다. Configuration.java

@Override
public int optionLength(String option) {
if (super.optionLength(option) > 0) {
return super.optionLength(option);
} else if (option.equals("-cmntpath") || option.equals("-charset") || option.equals("-header") ) {
return 2;
} else {
return 0;
}
}

이젠 charset 이나 header 등의 옵션도 잘 동작한다. 첨부 파일은 이렇게 수정한 l10ndoclet 이다.

덧글

  • 밤바 2011/09/22 13:33 # 삭제

    아 저도 일본 프로젝트할 때 이걸로 고민했었어요. 당시 Sun의 Java Doc은 일문판이 있었으니까... 작성 방법을 찾았더니 내부에서만 뭔가 툴을 쓴다고하고 공식적으로는 배포하지 않아서 관심 있으면 연락을 달라고 했던 기억이...
  • 오리대마왕 2011/09/24 21:13 #

    아 내부 도구가 있었군요. 아니, 그럼 자기네들도 needs를 알고 있었을텐데 공개 좀 해 주징...
※ 로그인 사용자만 덧글을 남길 수 있습니다.