Multilingual Support with Doxygen

When you build things like SDKs, there are times when you want to generate multilingual documentation. I recently had to create Japanese, English, and Korean documentation with Doxygen for work, so I am summarizing what I did.

Switching comments by language

In the Expert tab of Doxygen, define tags in ENABLED_SECTIONS and switch them depending on the target output. This time I defined the tags japanese and english. When writing comments, put language-specific text inside the corresponding tag. Any wording that is shared across languages should be left outside the tags.

When generating documentation with Doxygen, enabling the tag for the desired target language makes only the comments inside that tag active, so you get the documentation in the language you want.

/**
 * @file doxygen_multilingual.h
 */

/** @if japanese 処理が成功した時の戻り値 @endif */
/** @if english Return value on success @endif */
#define SUCCESS 0
/** @if japanese 処理が失敗した時の戻り値 @endif */
/** @if english Return value on failure @endif */
#define FAILURE -1

/**
 * @if japanese
 * @brief エラーコード
 * @endif
 * @if english
 * @brief Error code
 * @endif
 *
 * @see GetError
 * @since 1.0.0
 */
typedef enum _Error {
  /** @if japanese エラー無し @endif */
  /** @if english No error @endif */
  NO_ERROR,
  /** @if japanese ファイルがありません @endif */
  /** @if english File not be found @endif */
  CANNOT_FIND_THE_FILE
} Error;

/**
 * @if japanese
 * @brief 最新のエラーコードを取得します
 * @return 最新のエラーコードを返します
 * @endif
 * @if english
 * @brief Get latest error code
 * @return Returns latest error code
 * @endif
 * @since 1.0.0
 */
int Error GetError();

When you finally distribute the header to users, you may want to keep only the English comments, for example. I had that requirement as well, so in the end I wrote a Python script to remove unnecessary comments. The script below keeps only comments inside the english tag and removes the ones inside the japanese and korean tags.

#! /usr/bin/env python
# -*- coding: utf-8 -*-

import sys

if __name__ == '__main__':

    of = open(sys.argv[2], "wt")

    write_flag = True
    with open(sys.argv[1]) as source:
        for line in source:
            if line.find("@if japanese") > 0:
                if not line.find("@endif") > 0:
                    write_flag = False
                continue
            elif line.find("@if korean") > 0:
                if not line.find("@endif") > 0:
                    write_flag = False
                continue
            elif write_flag == False and line.find("@endif") > 0:
                write_flag = True
                continue
            elif line.find("@if english") > 0:
                #if not line.find("@endif") > 0:
                continue
            elif line.find("@endif") > 0:
                continue

            if write_flag:
                of.write(line)

    of.close()