Help us understand the problem. What is going on with this article?

Sphinxを用いたOpenModelica User's Guideの翻訳の四苦八苦

はじめに

OpenModelicaのUser's GuideはSphinxというツールで作成されています。
SphinxはPythonのドキュメント生成ツールで翻訳機能もあるため、User's Guideを日本語にするのに便利そうです。
この取り組みで初めてSphinxを触り、最初の1行を翻訳するまでにかなり四苦八苦したのでその履歴を残したいと思います。
非常に行き当たりばったりの取り組みをしたためまとまっていないことをご了承ください。

またSphinxの日本ユーザー会の皆様にSlack上で沢山の質問をさせて頂きエラーの見方や解決方法まで丁寧なアドバイスを頂きました。
この場で御礼を申し上げます。
本当にありがとうございます。

ドキュメント生成までの下準備

OpenModelicaはWSLでインストールするのが楽だったのでWSL環境で実施しています。

環境

Ubuntu 18.04 (WSL)
Python 3.6.9
sphinx-build 3.0.3

環境の構築

WSLのインストール

詳細は割愛

GithubからOpenModelicaリポジトリを取得

git clone --recursive https://openmodelica.org/git-readonly/OpenModelica.git OpenModelica

バージョンはv1.14.1が良かったので以下でチェックアウト
git checkout -b tag refs/tags/v1.14.1

Pythonのインストール

コマンドは忘れましたが、Python 3.6.9をインストールしました。
Windows MinGWの場合はPython2.7を使用するようなのでここら辺でPython2か3のどちらを使用するのか四苦八苦しました。

後はpipをインストール
sudo apt install python3-pip

関連ツールのインストール

以下のReadMEを見て関連ツールをインストール
https://github.com/OpenModelica/OpenModelica/blob/v1.14.1/doc/UsersGuide/README.md

Linux環境なら以下のコマンドで一括インストール出来ます。
-rオプションでテキストに書かれたファイルを一括でインストールできるようです。

cd (OpenModelicaのレポジトリがあるディレクト)/OpenModelica/doc/UsersGuide
pip install -r source/requirements.txt

テキストファイルの中身は以下
bibtexparser
gitpython
natsort
sphinx
sphinxcontrib-bibtex
sphinxcontrib-inlinesyntaxhighlight
ompython

htmlドキュメントのビルド

SphinxはreST(reStructuredText) 記法で書かれたドキュメントに対して処理を行い、綺麗なpdfやhtmlを生成します。
まずはhtmlを生成してみました。因みにOpenModelicaのReadMEにはドキュメント生成コマンドが無いので以下からはReadMEにない部分です。

make html

色々とエラーが出てきました。必要なパッケージはrequirements.txtに全部はいっていると思っていたのにそうでは無いのかもしれません。
ちゃんとエラーメッセージを残していませんが、以下を実行して足りないパッケージなどをインストールしました。

sudo add-apt-repository ppa:inkscape.dev/stable-daily
sudo apt-get update
sudo apt-get install inkscape
sudo apt-get install pandoc

エラーメッセージとしては以下のように出てくるので親切だと思います。

FileNotFoundError: [Errno 2] No such file or directory: 'pandoc': 'pandoc'

再度、htmlを作ってみます。

$make html  
cd source && ./tracreleases.py
sphinx-build -b html -t nomathjax -d build/doctrees   source build/html
TypeError: 'NoneType' object is not callable
~
Build finished. The HTML pages are in build/html.

TypeErrorというエラーは出てますがビルドできました。
htmlファイルはOpenModelica/doc/UsersGuide/buildフォルダに入っています。
以下のhtmlは生成されたファイル(index.html)で非常に綺麗なレイアウトです。
image.png

pdfドキュメントのビルド

pdfドキュメントを生成するにはmake latexpdfらしいです。
実行してみると以下のエラーが出ました。

(中略)
copying images... [ 54%] media/omnotebook-mathematical-modeling-with-characteristic-equation.copying images... [100%] media/datareconciliation_csv_report.png
Makefile:136: recipe for target 'latexpdf' failed
make: *** [latexpdf] Error 2

詳しい調査内容は忘れましたが、sudo apt-get install latexmkを実行して再度pdfを生成。
またエラーメッセージです。

! LaTeX Error: File `textalpha.sty' not found.

texalpha.styをインストールします。

tlmgr install textalpha.sty

再度pdfをビルドしますがエラーメッセージがでます。

! Package fontenc Error: Encoding file `lgrenc.def' not found.

! LaTeX Error: File `textalpha.sty' not found.
! Package inputenc Error: Unicode char α (U+3B1)
(inputenc)                not set up for use with LaTeX.

! Package inputenc Error: Unicode char θ (U+3B8)
(inputenc)                not set up for use with LaTeX.

! LaTeX Error: Unknown graphics extension: .svg.

Transcript written on OpenModelicaUsersGuide.log.
Latexmk: Missing input file: 'textalpha.sty' from line
  '! LaTeX Error: File `textalpha.sty' not found.'

Latexmk: Errors, so I did not complete making targets
Makefile:29: recipe for target 'OpenModelicaUsersGuide.pdf' failed
make[1]: *** [OpenModelicaUsersGuide.pdf] Error 12
make[1]: Leaving directory '/(OpenModelicaのリポジトリ)/OpenModelica/doc/UsersGuide/build/latex'
Makefile:136: recipe for target 'latexpdf' failed
make: *** [latexpdf] Error 2

しかし、pdfはビルドされています。
ここは諦めて翻訳に進みました。

翻訳に挑戦

以下のサイト様を参考にさせて頂きました。
https://tk0miya.hatenablog.com/entry/20111203/p1

rstファイルからpotファイル、poファイル、moファイルと三段階ファイルを生成して、その中のpoファイルに元の文に対応する翻訳文を入れていくようです。
image.png

簡単な文書を翻訳

簡単なテンプレートがあるので、それを以下のように翻訳してみます。

  • 翻訳前
    image.png

  • 翻訳後
    image.png

あまり詳細を解説できないので実行コマンドを書いていきます。
1. sphinx-quickstart
2. source/conf.pyに以下を追加
    locale_dirs = ['local']
    gettext_compact = False
3. make gettext
4. sphinx-intl update -p build/gettext -l ja
5. source/local/ja/LC_MESSAGES/index.po内のmsgstrへ翻訳文を追加
    #: ../../source/index.rst:7
    msgid "Welcome to Test1's documentation!"
    msgstr "Test1のドキュメントへようこそ"
6. make -e SPHINXOPTS="-D language='ja'" html
7. build\html\index.htmlを開く
8. できた

OpenModelicaのUser's Guideを翻訳

この工程でかなり四苦八苦したのでちゃんとまとめられておりません。
トライ&エラーを全て書くのも大変なのでポイントだけ書いていきます。
もし以下を実施して同様に翻訳できなかったら申し訳ございません。

またここから以下のSphinxの日本ユーザー会の皆様にSlack上で質問させて頂きました。
https://sphinx-users.jp/howtojoin.html

make gettextのエラー

conf.pyファイルに以下を追加

locale_dirs = ['local']
gettext_compact = False

エラー発生

make gettext
sphinx-intl update -p build/gettext -l ja
#エラー内容
TypeError: category must be a Warning subclass, not 'str'

conf.pyの"""となっているところをr"""にしたら解決しました。

'preamble': """
\usepackage{bookmark}
""",

```修正後
'preamble': r"""
\usepackage{bookmark}
""",

これは\uをunicode文字列の16進表記として解釈してエラーになったそうです。
rをつけて単なるバックスラッシュとして解釈するように変えることでうまく行くようになったとアドバイス頂きました。

pdf作成時のエラー

ようやくpdf生成のコマンドに進めました。
しかし以下のコマンドでエラーとなりました。

$make -e SPHINXOPTS="-D language='ja'" latexpdf

! Package fontenc Error: Encoding file `lgrenc.def' not found.  
(fontenc)                You might have misspelt the name of the encoding.  

以下をインストール

sudo apt-get install texlive-lang-greek

該当のエラーは消えましたがまだ以下のようなエラーが残っています。

! LaTeX Error: Unknown graphics extension: .svg.

どうにもsvgファイルというのは取り扱いにくいようです。
様々な対策をしているうちにMakefile内にpdfを生成するためのコマンドが特別に用意されていることを見つけました。
この中でsvgの処理をしています。

pdf: latex
    $(MAKE) addedPdfs
    cp source/ProfilingTest_*.pdf build/latex/.
    sed -i "s/usepackage.utf8..inputenc./usepackage[utf8x]{inputenc}/" build/latex/OpenModelicaUsersGuide.tex
    sed -i -e "/^ *\\\\DeclareUnicodeCharacter/d" build/latex/OpenModelicaUsersGuide.tex
    # sphinx seems to only handle .* extension for images?
    sed -i "s,{\(media/[A-Za-z_0-9.-]*\)[.][*],{`pwd`/source/\1.pdf,g" build/latex/OpenModelicaUsersGuide.tex
    sed -i "s,{ProfilingTest_prof[.]\([^.]*\)[.]thumb}[.]svg,{`pwd`/source/ProfilingTest_prof-\1-thumb}.pdf,g" build/latex/OpenModelicaUsersGuide.tex
    (cd build/latex && latexmk -pdf OpenModelicaUsersGuide.tex)
source/logo.pdf: source/logo.svg
    inkscape -f $< -A $@
source/media/systemoverview.pdf: source/media/systemoverview.svg
    inkscape -f $< --export-pdf $@
%.pdf: %.svg
    inkscape -f $< --export-pdf $@
    FNAME=`echo $@ | sed "s/[.]/-/g" | sed "s/-pdf/.pdf/g"`; if test "$$FNAME" != "$@"; then cp -a "$@" "$$FNAME"; fi
source/openmodelica.bib: resolve-crossref.py ../bibliography/openmodelica.bib
    ./resolve-crossref.py "../bibliography/openmodelica.bib" source/openmodelica.bib
source/interface.inc: interface.mos
    @mkdir -p tmp
    $(OPENMODELICA_ROOT)/build/bin/omc -g=MetaModelica -d=nogen interface.mos
    mv interface.inc $@

上記を使えば(make pdf)今までmake latexpdfででていたエラーも無くpdfが生成できます。
気がつかなかった。。。

意気揚々と翻訳コマンドを実行します。しかしエラーがでます。

$make -e SPHINXOPTS="-D language='ja'" latexpdf

! LaTeX Error: This file needs format `pLaTeX2e'    
               but this is `LaTeX2e'.

どうにもpdflatexが使われているのですが、platexのほうがおすすめのようです。
またアドバイスを頂いて以下のようにMakefileを修正しました。

修正前   (cd build/latex && latexmk -pdf OpenModelicaUsersGuide.tex)
修正後   (cd build/latex && $(MAKE) all-pdf)

latexmkによってpdflatexが使われるように設定されていたようです。

これでpdfを生成するとようやく翻訳できました。

  • 翻訳前
    image.png

  • 翻訳後
    image.png

綺麗にできています。

まとめ

かなり苦労しましたが何とか翻訳ができました。
これから進めるとまた別の苦労があるかもしれませんがとりあえず何とか一歩ずつ進める体制ができました。
アドバイス頂きましたSphinxの日本ユーザー会の皆様とユーザー会を紹介して頂いた方に厚く御礼申し上げます。

UedaShigenori
CAEの普及と活用に興味があります。 プロフィールは以下から https://connpass.com/user/uedashige/
https://github.com/UedaShigenori
Why not register and get more from Qiita?
  1. We will deliver articles that match you
    By following users and tags, you can catch up information on technical fields that you are interested in as a whole
  2. you can read useful information later efficiently
    By "stocking" the articles you like, you can search right away
Comments
No comments
Sign up for free and join this conversation.
If you already have a Qiita account
Why do not you register as a user and use Qiita more conveniently?
You need to log in to use this function. Qiita can be used more conveniently after logging in.
You seem to be reading articles frequently this month. Qiita can be used more conveniently after logging in.
  1. We will deliver articles that match you
    By following users and tags, you can catch up information on technical fields that you are interested in as a whole
  2. you can read useful information later efficiently
    By "stocking" the articles you like, you can search right away
ユーザーは見つかりませんでした