はじめに

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

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)で非常に綺麗なレイアウトです。

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ファイルに元の文に対応する翻訳文を入れていくようです。

簡単な文書を翻訳

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

翻訳前
翻訳後

あまり詳細を解説できないので実行コマンドを書いていきます。
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を生成するとようやく翻訳できました。
最終的な実行コマンド

make -e SPHINXOPTS="-D language='ja'" pdf

翻訳前
翻訳後

綺麗にできています。

文字化け、不具合の修正

2020/12/23追記　ここから

日本語でpdfを生成すると色々と文字化けしてしまいました。

文字化け1

正しい状態
>>> getInstallationDirectoryPath() + "/share/doc/omc/testmodels/"
"«OPENMODELICAHOME»/share/doc/omc/testmodels/"

文字化け状態
>>> getInstallationDirectoryPath() + "/share/doc/omc/testmodels/"
"^^c2^^abOPENMODELICAHOME^^c2^^bb/share/doc/omc/testmodels/"

○解決策
「sphinxcontribopenmodelica.py」の中に文字化けの原因となっている「«」と「»」があったので、「<<」と「>>」に置き換えてお茶を濁しました。

文字化け2

正しい状態　→　文字化け
©　→　Âl’
®　→　Âo
ö　→　Ã ˝

○解決策
conf.pyの最後に「latex_engine = 'uplatex' 」を追記。
pdf生成にuplatexを使用することで文字化けは無くなりました。
しかし以下の不具合1が発生しました。

不具合1

文字化け2で出てきた特殊文字の前後にスペースが入る問題が発生しました。

正しい状態　→　不具合
Linköpings　→　Link ö pings

○解決策
uplatexが2017だったので2020に変更。
WSLの場合、apt-get install texliveコマンドを使用しても上手くuplatexに切り替わりませんでした。
以下のサイト様を参考にtexlive2020をフルインストールしました。
texlive2020(basic)のインストール on WSL
https://tex2e.github.io/blog/latex/texlive2020-in-wsl

インストール後、パスは自分で設定しないといけないため~/.profileにtexliveのパスを指定。

PATH="$PATH:/usr/local/texlive/2020/bin/x86_64-linux"

uplatex --versionで最新版になっていることを確認。

$ uplatex --version
e-upTeX 3.14159265-p3.8.3-u1.26-191112-2.6 (utf8.uptex) (TeX Live 2020)
kpathsea version 6.3.2
ptexenc version 1.3.8
Copyright 2020 D.E. Knuth.
There is NO warranty.  Redistribution of this software is
covered by the terms of both the e-upTeX copyright and
the Lesser GNU General Public License.
For more information about these matters, see the file
named COPYING and the e-upTeX source.
Primary author of e-upTeX: Peter Breitenlohner.

上記でようやく文字化け関係のエラーが無くなりました。

追記した内容についてもSphinxの日本ユーザー会の皆様に沢山のアドバイス頂きました。
アドバイスが無いと絶対に解決できなかったと思います。
本当にありがとうございました。

2020/12/23追記　ここまで

まとめ

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

注意事項

本投稿の技術的な内容を利用して翻訳活動を行う際には対象の著作権に注意してください。

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