publican とは？
publicanは、DocBook XMLに基づくソース公開ツールです。
RedHatやFedoraなどで使用されています。
ユーザガイドなどの文書を翻訳者が自分で翻訳したPOファイルを元に製版してHTMLやPDFなどにするために使われています。
MantisBTの日本語ドキュメントが欲しいよ！
publicanの記事を書くことになったのは、MantisBTをバージョンアップしたら
まるっきりUIが変わっており、マニュアル欲しい！となったのがきっかけでした。
MantisBTのドキュメントには、英語のドキュメントしかない
githubのmantisbtのリポジトリには、docbookが含まれています。
mantisbt/docbook
どうやら「publican build --formats=pdf,html --langs=ja-JP」とビルドすると良いのでは？
ということでやってみます。
日本語ドキュメントを生成してみる
1. ビルド環境を用意する
先ずは、ビルド環境を用意します。
ベースのOSは、centos7とubuntu16.04で試した結果、ubuntuだとすんなり行きましたので
ubuntuで進めることにしました。
dockerで作って行きます。
- ubuntuで日本語を扱える様にする
- 最終的にAWS S3にアップロードするためにcliをインストール
- mantisbtのリポジトリをcloneするので、gitをインストール
- makeしたくなるかもしれないので、build-essentialを入れておく（makeしなくても大丈夫だけど）
FROM ubuntu:16.04
ENV TZ Asia/Tokyo
ENV LANG ja_JP.UTF-8
ENV LC_ALL ja_JP.UTF-8
ENV LANGUAGE ja_JP:ja
RUN apt-get update \
&& apt-get install -y --no-install-recommends \
language-pack-ja-base \
language-pack-ja \
ibus-mozc \
git \
build-essential \
publican \
awscli \
&& apt-get -y clean \
&& rm -rf /var/lib/apt/lists/*
CMD /bin/bash
ということで、環境が出来上がりました。
こうして作ったdockerコンテナにログインして作業を続けます。
2. publicanのバージョンを確認する
どうやら、v4.3.2の様ですので、公式マニュアルも4.3を見れば良いですね
# publican -v
version=v4.3.2
3. 作業前の注意事項
ここから先、ファイルの種類（名前と拡張子）が似ているので間違い易いのでご注意下さい。
- potファイル
- poファイル
pot作って、po作って、翻訳して、ビルドする流れになります。
4. mantisbtのリポジトリをclone
docbookディレクトリに、Admin_GuideとDevelopers_Guideがあります。
# git clone https://github.com/mantisbt/mantisbt.git
Cloning into 'mantisbt'...
remote: Enumerating objects: 83, done.
remote: Counting objects: 100% (83/83), done.
remote: Compressing objects: 100% (76/76), done.
remote: Total 109083 (delta 15), reused 18 (delta 7), pack-reused 109000
Receiving objects: 100% (109083/109083), 68.82 MiB | 4.64 MiB/s, done.
Resolving deltas: 100% (86161/86161), done.
Checking connectivity... done.
# cd ./mantisbt/docbook
# ls
Admin_Guide Developers_Guide Makefile README.md erd
5. Admin_Guideを翻訳してみる
Admin_Guideのディレクトリには、Makefileと、en-US（英語版）のディレクトリ、そしてpublicanの設定ファイルである、publican.cfgがあります。
このAdmin_Guideのディレクトリが作業するディレクトリになります。
# cd ./Admin_Guide
# ls
Makefile en-US publican.cfg
6. potファイルを生成する
en-USディレクトリ配下のXMLファイルからポータブルオブジェクトテンプレート（POT）ファイル を生成します。
publican update_pot コマンドを実行します。
やってみましょう！
# pwd
/root/mantisbt/docbook/Admin_Guide
# publican update_pot
Processing file en-US/About.xml
Processing file en-US/Admin_Guide.xml
deleted empty pot file: pot/Admin_Guide.pot
Processing file en-US/Authentication.xml
Processing file en-US/Author_Group.xml
Processing file en-US/Book_Info.xml
Processing file en-US/Configuration.xml
Processing file en-US/Contributing.xml
Processing file en-US/Customizing.xml
Processing file en-US/Installation.xml
Processing file en-US/Page_Descriptions.xml
Processing file en-US/Preface.xml
Processing file en-US/Project_Management.xml
Processing file en-US/Revision_History.xml
Processing file en-US/Troubleshooting.xml
Processing file en-US/User_Management.xml
Processing file en-US/Workflow.xml
Processing file en-US/config/antispam.xml
Processing file en-US/config/api.xml
Processing file en-US/config/auth.xml
Processing file en-US/config/bughistory.xml
Processing file en-US/config/bugnote.xml
Processing file en-US/config/cookies.xml
Processing file en-US/config/customfields.xml
Processing file en-US/config/database.xml
Processing file en-US/config/date.xml
Processing file en-US/config/defaults.xml
Processing file en-US/config/display.xml
Processing file en-US/config/duedate.xml
Processing file en-US/config/email.xml
Processing file en-US/config/fields.xml
Processing file en-US/config/filters.xml
Processing file en-US/config/html.xml
Processing file en-US/config/issues.xml
Processing file en-US/config/language.xml
Processing file en-US/config/logging.xml
Processing file en-US/config/misc.xml
Processing file en-US/config/myview.xml
Processing file en-US/config/news.xml
Processing file en-US/config/path.xml
Processing file en-US/config/relationship.xml
Processing file en-US/config/reminders.xml
Processing file en-US/config/security.xml
Processing file en-US/config/settings.xml
Processing file en-US/config/signup.xml
Processing file en-US/config/speed.xml
Processing file en-US/config/sponsorship.xml
Processing file en-US/config/status.xml
Processing file en-US/config/subprojects.xml
Processing file en-US/config/summary.xml
Processing file en-US/config/time.xml
Processing file en-US/config/timetracking.xml
Processing file en-US/config/timezone.xml
Processing file en-US/config/uploads.xml
Processing file en-US/config/user.xml
Processing file en-US/config/version.xml
Processing file en-US/config/view.xml
Processing file en-US/config/webserver.xml
Processing file en-US/config/wiki.xml
# ls
Makefile en-US pot publican.cfg
# ls pot/
About.pot Book_Info.pot Customizing.pot Preface.pot Troubleshooting.pot config
Authentication.pot Configuration.pot Installation.pot Project_Management.pot User_Management.pot
Author_Group.pot Contributing.pot Page_Descriptions.pot Revision_History.pot Workflow.pot
無事、potファイルが生成されました！
7. poファイルを生成する
特定の言語への翻訳を開始するために、potファイルからポータブルオブジェクト（PO）ファイル を生成します。
publican update_po --langs=ja-JP コマンドを実行します。
ここで、オプションの--langsに、ターゲット言語のコードを指定しますが、言語コードを確認して下さい。
コンマで区切られた複数の言語コードを指定して、一度に複数の言語のPOファイルを生成できます。
例えば： publican update_po --langs=en-US,ja-JPという具合ですね
やってみましょう！
# pwd
/root/mantisbt/docbook/Admin_Guide
# publican update_po --langs=ja-JP
firstname is a mandatory argument at /usr/bin/publican line 1194.
あれ？引数にfirstname(名)が必要だと言われるのでhelpを確認しました。
# pwd
/root/mantisbt/docbook/Admin_Guide
# publican --help update_po
update_po
Update the PO files
Options:
--help Display help message
--config=s Use a nonstandard config file
--common_config=s Override path to Common_Config directory
--common_content=s Override path to Common_Content directory
--nocolours Disable ANSI colourisation of logging.
--quiet Disable all logging.
--brand_dir=s Directory to source brand files from.
--allow_network Allow the XML and XSLT processing to access the network. Defaults off.
--langs=<LANGS> Comma-separated list of languages, for example: en-US,de-DE,all
--msgmerge Use gettext's msgmerge for POT/PO merging.
--firstname=<FIRSTNAME> firstname to use for a revision.
--surname=<SURNAME> surname to use for a revision.
--email=<EMAIL> email to use for a revision.
--previous Keep previous msgid when fuzzy matches are detected in PO updates.
よしよし
# pwd
/root/mantisbt/docbook/Admin_Guide
# publican update_po --langs=ja-JP --firstname=tarou
surname is a mandatory argument at /usr/bin/publican line 1194.
今度は？引数にsurname(姓)が必要だと言われる
# pwd
/root/mantisbt/docbook/Admin_Guide
# publican update_po --langs=ja-JP --firstname=tarou --surname=qitta
email is a mandatory argument at /usr/bin/publican line 1194.
今度は？引数にemailが必要だと言われる
もう一度に教えてくれよ・・・
# pwd
/root/mantisbt/docbook/Admin_Guide
# publican update_po --langs=ja-JP --firstname=tarou --surname=qitta --email=qitta.hoge@example.com
Processing file pot/About.pot -> ja-JP/About.po
Processing file pot/Authentication.pot -> ja-JP/Authentication.po
Processing file pot/Author_Group.pot -> ja-JP/Author_Group.po
Processing file pot/Book_Info.pot -> ja-JP/Book_Info.po
Processing file pot/Configuration.pot -> ja-JP/Configuration.po
Processing file pot/Contributing.pot -> ja-JP/Contributing.po
Processing file pot/Customizing.pot -> ja-JP/Customizing.po
Processing file pot/Installation.pot -> ja-JP/Installation.po
Processing file pot/Page_Descriptions.pot -> ja-JP/Page_Descriptions.po
Processing file pot/Preface.pot -> ja-JP/Preface.po
Processing file pot/Project_Management.pot -> ja-JP/Project_Management.po
Processing file pot/Revision_History.pot -> ja-JP/Revision_History.po
Processing file pot/Troubleshooting.pot -> ja-JP/Troubleshooting.po
Processing file pot/User_Management.pot -> ja-JP/User_Management.po
Processing file pot/Workflow.pot -> ja-JP/Workflow.po
Processing file pot/config/antispam.pot -> ja-JP/config/antispam.po
Processing file pot/config/api.pot -> ja-JP/config/api.po
Processing file pot/config/auth.pot -> ja-JP/config/auth.po
Processing file pot/config/bughistory.pot -> ja-JP/config/bughistory.po
Processing file pot/config/bugnote.pot -> ja-JP/config/bugnote.po
Processing file pot/config/cookies.pot -> ja-JP/config/cookies.po
Processing file pot/config/customfields.pot -> ja-JP/config/customfields.po
Processing file pot/config/database.pot -> ja-JP/config/database.po
Processing file pot/config/date.pot -> ja-JP/config/date.po
Processing file pot/config/defaults.pot -> ja-JP/config/defaults.po
Processing file pot/config/display.pot -> ja-JP/config/display.po
Processing file pot/config/duedate.pot -> ja-JP/config/duedate.po
Processing file pot/config/email.pot -> ja-JP/config/email.po
Processing file pot/config/fields.pot -> ja-JP/config/fields.po
Processing file pot/config/filters.pot -> ja-JP/config/filters.po
Processing file pot/config/html.pot -> ja-JP/config/html.po
Processing file pot/config/issues.pot -> ja-JP/config/issues.po
Processing file pot/config/language.pot -> ja-JP/config/language.po
Processing file pot/config/logging.pot -> ja-JP/config/logging.po
Processing file pot/config/misc.pot -> ja-JP/config/misc.po
Processing file pot/config/myview.pot -> ja-JP/config/myview.po
Processing file pot/config/news.pot -> ja-JP/config/news.po
Processing file pot/config/path.pot -> ja-JP/config/path.po
Processing file pot/config/relationship.pot -> ja-JP/config/relationship.po
Processing file pot/config/reminders.pot -> ja-JP/config/reminders.po
Processing file pot/config/security.pot -> ja-JP/config/security.po
Processing file pot/config/settings.pot -> ja-JP/config/settings.po
Processing file pot/config/signup.pot -> ja-JP/config/signup.po
Processing file pot/config/speed.pot -> ja-JP/config/speed.po
Processing file pot/config/sponsorship.pot -> ja-JP/config/sponsorship.po
Processing file pot/config/status.pot -> ja-JP/config/status.po
Processing file pot/config/subprojects.pot -> ja-JP/config/subprojects.po
Processing file pot/config/summary.pot -> ja-JP/config/summary.po
Processing file pot/config/time.pot -> ja-JP/config/time.po
Processing file pot/config/timetracking.pot -> ja-JP/config/timetracking.po
Processing file pot/config/timezone.pot -> ja-JP/config/timezone.po
Processing file pot/config/uploads.pot -> ja-JP/config/uploads.po
Processing file pot/config/user.pot -> ja-JP/config/user.po
Processing file pot/config/version.pot -> ja-JP/config/version.po
Processing file pot/config/view.pot -> ja-JP/config/view.po
Processing file pot/config/webserver.pot -> ja-JP/config/webserver.po
Processing file pot/config/wiki.pot -> ja-JP/config/wiki.po
Processing file ja-JP/Revision_History.xml -> ja-JP/Revision_History.xml
# ls
Makefile en-US ja-JP pot publican.cfg
# ls ja-JP/
About.po Book_Info.po Customizing.po Preface.po Revision_History.xml Workflow.po
Authentication.po Configuration.po Installation.po Project_Management.po Troubleshooting.po config
Author_Group.po Contributing.po Page_Descriptions.po Revision_History.po User_Management.po
ようやく、poファイルが生成できました。
8. 生成されたpoファイルを見てみる
# pwd
/root/mantisbt/docbook/Admin_Guide
# cat ja-JP/About.po
msgid ""
msgstr ""
"Project-Id-Version: 0\n"
"POT-Creation-Date: 2020-05-08 15:50+0900\n"
"PO-Revision-Date: 2020-05-08 15:50+0900\n"
"Last-Translator: Automatically generated\n"
"Language-Team: None\n"
"Language: en-US \n"
"MIME-Version: 1.0\n"
"Content-Type: application/x-publican; charset=UTF-8\n"
"Content-Transfer-Encoding: 8bit\n"
"X-Generator: Publican v4.3.2\n"
msgid "About MantisBT"
msgstr "MantisBTについて"
msgid "What is MantisBT?"
msgstr ""
~~~~ 省略 ~~~~
msgstr に何も入ってないので、これを入れるのが、翻訳者の作業です。
9. poファイルを編集する
翻訳作業に入るわけですが、翻訳エディタにはPoeditを使いました。
「Poedit」を使えば、英語以外にも様々な言語を日本語にできるので、海外の人気テーマや便利なプラグインを日本語化する場合にオススメの定番ツールらしいです。
無料では、翻訳できる数に制限があります。
先程のAbout.poを翻訳してみました。
Languageが、ja_JP
msgstrに、日本語に翻訳した内容が入っています。
msgid ""
msgstr ""
"Project-Id-Version: 0\n"
"POT-Creation-Date: 2020-05-08 15:50+0900\n"
"PO-Revision-Date: 2020-05-08 15:50+0900\n"
"Last-Translator: Automatically generated\n"
"Language-Team: None\n"
"Language: ja_JP \n"
"MIME-Version: 1.0\n"
"Content-Type: application/x-publican; charset=UTF-8\n"
"Content-Transfer-Encoding: 8bit\n"
"X-Generator: Publican v4.3.2\n"
msgid "About MantisBT"
msgstr "MantisBTについて"
msgid "What is MantisBT?"
msgstr ""
~~~~ 省略 ~~~~
10. いざビルド！
ビルドには、publican build --formats=html --langs=ja-JPコマンドを実行します。
--formatsには、htmlの他にも、html-singleやpdfをコンマ区切りで指定出来ます。
本を複数ページのHTMLにしたり、単一ページのHTMLにしたり、PDF形式で作成出来ます。
ではやってみましょう！
1ファイルしか翻訳完成していないので、WARNINGが一杯出ますが割愛します。
# publican build --formats=html --langs=ja-JP
Setting up ja-JP
Merging ja-JP/About.po >> en-US/About.xml -> tmp/ja-JP/xml_tmp//About.xml
WARNING: Un-translated message in PO file.
17: "What is MantisBT?"
~~~~ 省略 ~~~~
Beginning work on ja-JP
DTD Validation OK
Starting html
Using XML::LibXSLT on /usr/share/publican/xsl/html.xsl
Finished html
# ls
Makefile en-US ja-JP pot publican.cfg tmp
# ls tmp/
ja-JP
# ls tmp/ja-JP/
html xml xml_tmp
# ls tmp/ja-JP/html/
Common_Content admin.customize.customfields.linking.html
admin.about.download.html admin.customize.customfields.localize.html
admin.about.history.html admin.customize.customfuncs.example.html
admin.about.html admin.customize.customfuncs.html
admin.about.license.html admin.customize.email.html
admin.about.name.html admin.customize.enums.html
admin.about.news.html admin.customize.html
admin.about.support.html admin.customize.status.html
admin.about.versioning.html admin.install.backups.html
admin.about.who.html admin.install.config.html
admin.auth.basic.html admin.install.html
admin.auth.deprecated.html admin.install.new.html
admin.auth.html admin.install.postcommon.html
admin.auth.http.html admin.install.postinstall.html
admin.auth.ldap.html admin.install.postupgrade.html
admin.config.antispam.html admin.install.preinstall.html
admin.config.api.html admin.install.requirements.client.html
admin.config.auth.html admin.install.requirements.html
admin.config.auth.ldap.html admin.install.requirements.software.html
admin.config.bughistory.html admin.install.uninstall.html
admin.config.bugnote.html admin.install.upgrade.html
admin.config.cookies.html admin.lifecycle.html
admin.config.customfields.html admin.lifecycle.status.html
admin.config.database.html admin.lifecycle.workflow.html
admin.config.date.html admin.lifecycle.workflow.thresholds.html
admin.config.defaults.html admin.pages.account.apitokens.html
admin.config.display.html admin.pages.account.html
admin.config.duedate.html admin.pages.account.managecolumns.html
admin.config.email.html admin.pages.account.profiles.html
admin.config.fields.html admin.pages.assigntome.html
admin.config.filters.html admin.pages.close.html
admin.config.html admin.pages.delete.html
admin.config.html.html admin.pages.filter.html
admin.config.issues.html admin.pages.html
admin.config.issues.limitedview.html admin.pages.issueedit.html
admin.config.issues.limitreporters.html admin.pages.issuestatus.html
admin.config.language.html admin.pages.issueview.html
admin.config.logging.html admin.pages.main.html
admin.config.misc.html admin.pages.manage.config.email.html
admin.config.myview.html admin.pages.manage.config.html
admin.config.news.html admin.pages.manage.config.transitions.html
admin.config.path.html admin.pages.manage.customfields.html
admin.config.relationship.html admin.pages.manage.html
admin.config.reminders.html admin.pages.manage.profiles.html
admin.config.security.html admin.pages.manage.projects.html
admin.config.settings.html admin.pages.monitor.html
admin.config.signup.html admin.pages.news.html
admin.config.speed.html admin.pages.reopen.html
admin.config.sponsorship.html admin.pages.resolve.html
admin.config.status.html admin.project.graphs.html
admin.config.subprojects.html admin.project.html
admin.config.summary.html admin.project.roadmap.html
admin.config.time.html admin.project.summary.html
admin.config.timetracking.html admin.project.timetracking.html
admin.config.timezone.html admin.troubleshooting.html
admin.config.uploads.html admin.user.access.html
admin.config.users.html admin.user.autocreate.html
admin.config.version.html admin.user.delete.html
admin.config.view.html admin.user.enable.html
admin.config.webserver.html admin.user.html
admin.config.wiki.html admin.user.impersonation.html
admin.contributing.blog.html admin.user.passwordchange.html
admin.contributing.html admin.user.passwordreset.html
admin.contributing.integrate.html admin.user.prefs.html
admin.contributing.share.html admin.user.profiles.html
admin.customize.customfields.defaults.html admin.user.pruning.html
admin.customize.customfields.definitions.html admin.user.signup.html
admin.customize.customfields.dynamic.custom.html appe-Admin_Guide-Revision_History.html
admin.customize.customfields.dynamic.html html
admin.customize.customfields.editing.html images
admin.customize.customfields.html index.html
どうやら、無事成功した様です。
- 翻訳前
- 翻訳後
おお！ 1. MantisBTについてと翻訳されていますね！
最後に
最終的に、gitlabのciで、ビルドを行うことにしたので
今回作ったビルド環境のdockerイメージをdocker hubに公開しています。
kaihei777/publican_build_docker_container
S3で静的ウェブサイトとしてホスティング公開してみましたが、imagesへの参照パスが
Common_Content/images//image_left.png
この様に、//となってしまい、404になってしまうので
sedで置換してます。
..gitlab-ci.yml
image: kaihei777/publican_build_docker_container:ubuntu16.04
stages:
- build
variables:
DEPLOYMENT_ROLE: "arn:aws:iam::000000000000:role/GitLab-CI-Role"
S3_BUCKET_NAME: "mantisbt.docbook.example.net"
before_script:
- KST=(`aws sts assume-role --role-arn ${DEPLOYMENT_ROLE} --role-session-name "deployment-${CI_PROJECT_NAME}" --query '[Credentials.AccessKeyId,Credentials.SecretAccessKey,Credentials.SessionToken]' --output text`)
- unset AWS_ACCESS_KEY_ID
- unset AWS_SECRET_ACCESS_KEY
- unset AWS_SECURITY_TOKEN
- export AWS_ACCESS_KEY_ID=${KST[0]}
- export AWS_SECRET_ACCESS_KEY=${KST[1]}
- export AWS_SESSION_TOKEN=${KST[2]}
- export AWS_SECURITY_TOKEN=${KST[2]}
deploy_docbook:
stage: build
script:
- echo "===== deploying to ${CI_ENVIRONMENT_NAME} environment ====="
- cd ${CI_PROJECT_DIR}/docbook/Admin_Guide
- publican build --formats=html --langs=ja-JP
- ls
- cd ${CI_PROJECT_DIR}/docbook/Admin_Guide/tmp/ja-JP/html
- find . -name "*.html" | xargs sed -i 's/Common_Content\/images\/\/image_left.png/Common_Content\/images\/image_left.png/g'
- find . -name "*.html" | xargs sed -i 's/Common_Content\/images\/\/image_right.png/Common_Content\/images\/image_right.png/g'
- aws s3 sync . s3://$S3_BUCKET_NAME --delete --exclude ".git/*" --exclude ".gitlab-ci.yml" --exclude "README.md"
Crowdinでチームでの共同作業で翻訳
CrowdinでProjectを管理すると、チームで翻訳作業を分担できます。
Crowdinは、有料なのですが、OSSの翻訳の場合は、申請すると無料で利用できる様になる様です。
Poeditは、Crowdinと連携できます。