guide/LDP_man-pages.rst

   1 ========================
   2 LDP man-pages 翻訳ガイド
   3 ========================
   4
   5 LDP man-pages では、翻訳に po4a を利用しています。
   6 そのため、手順が他の翻訳方法と少し異なっています。
   7
   8 .. _ldp_preparation:
   9
  10 準備
  11 ====
  12
  13 po4a を利用しているので、インストールしておきます。
  14 以下は Debian/Ubuntu の場合。
  15 他のディストリビューションの場合も po4a をインストールすれば大丈夫だと思います。
  16
  17 .. code-block:: console
  18
  19    $ apt-get install po4a
  20
  21 .. note::
  22
  23    po4a のバージョンにより roff マクロの認識や文字列抽出方法に違いがあることを
  24    確認しています。以下の環境で動作を確認しています (2021年3月時点)。
  25
  26    * po4a 0.57 (Ubuntu 20.04 focal)
  27    * po4a 0.55 (Debian 10 buster)
  28    * po4a 0.52 (Ubuntu 18.04 focal)
  29
  30 翻訳更新の動作確認を行っておきます。
  31 全ファイルを処理するので多少時間がかかります (2〜3分くらい)。
  32
  33 .. code-block:: console
  34
  35    $ cd manual/LDP_man-pages
  36    $ make setup
  37    $ make
  38    $ git status
  39
  40 全部のコマンドがエラーなく終了すること、
  41 最後の ``git status`` コマンドで更新されているファイルがないこと、
  42 を確認してください。
  43 ``git status`` の出力で更新されているファイルがある場合は、
  44 そのまま翻訳作業を進めると、意図しないファイルも更新してしまうことがあるので、
  45 メーリングリストで相談するなどして対応を検討しましょう。
  46 作業漏れ以外の可能性もあり、たとえば、 po4a のバージョンが変わって
  47 PO ファイルへの抜き出し方法が変わることもあります。
  48
  49 翻訳方法
  50 ========
  51
  52 LDP man-pages では、翻訳に po4a を利用しています。
  53
  54 roff ファイルと PO ファイルの変換には、 roff ファイルと PO ファイルが 1:1
  55 になっているわけではなく、 po4a ファイルはカテゴリー毎に用意され、
  56 ひとつの po4a ファイルには複数の roff ファイルが含まれています。
  57
  58 おおまかな流れは以下のようになります。
  59
  60 1. 翻訳したい man page に対応する PO ファイルを特定する
  61 2. PO ファイルで翻訳を行う
  62 3. draft の man page を生成する
  63
  64 ファイルの対応付けがこのようになっているのは、
  65 似た roff ファイルには似た文が含まれていてカテゴリー単位の方が翻訳が
  66 効率化されること、逆に全 roff ファイルを一つの PO ファイルにまとめて
  67 しまうと本来違う意味で解釈すべき文が同じエントリーになってしまう可能性
  68 があり、それを回避するため、という点からです。
  69 この対応付けは、もともと LDP man-pages のフランス語翻訳チームが
  70 公開していた perkamon をベースにしています。
  71
  72 翻訳と draft への変換
  73 ---------------------
  74
  75 ja.po と man page の関係
  76 ~~~~~~~~~~~~~~~~~~~~~~~~
  77
  78 一つの po ファイルは、 LDP\_man-pages の複数の man page に対応しています。
  79 man page に対応する po ファイルを特定するには、以下のコマンドを実行します。
  80
  81 .. code-block:: console
  82
  83    $ ./tools/identify-po.sh strptime.3
  84    strptime.3 -> po4a/time/po/ja.po
  85
  86 上記の場合、strptime.3 が含まれる po ファイル (ja.po) は time 以下にあります。
  87 po4a/time/po/ja.po を翻訳することになります。
  88
  89 翻訳
  90 ~~~~
  91
  92 上記で特定した ja.po を翻訳します。
  93
  94 エディタは po ファイルに対応しているものが便利です。
  95
  96 * Emacs を使っていれば Emacs の po-mode が便利です。
  97 * gedit も PO ファイルをきれいに色付けしてくれるので、作業しやすいと思います。
  98
  99 draft page の生成
 100 ~~~~~~~~~~~~~~~~~
 101
 102 ja.po から draft を生成するには以下のいずれかを実行します (どちらも同じです)。
 103 更新を行った PO ファイルのみが変換されます。
 104
 105 .. code-block:: console
 106
 107    $ make
 108
 109 または
 110
 111 .. code-block:: console
 112
 113    $ make translate
 114
 115 どのファイルが更新されたかは git status で確認して下さい。
 116
 117 .. code-block:: console
 118
 119    $ git status .
 120
 121 デフォルトでは、翻訳率 80% 以上のページが生成されます。
 122 80% にしている理由は、ある程度日本語混じりの draft page を見ながら翻訳する方が
 123 全体の文脈をつかみやすいためです。全部翻訳できたかは、下記の「翻訳状況の確認」
 124 の方法で確認できるので、翻訳率 100% を閾値にする必要はないと考えています。
 125
 126 生成された draft page を man コマンドで整形して、内容を確認します。
 127 修正を行う際は、 ja.po を更新 -> draft page の生成 -> 内容の確認、を繰り返します。
 128
 129 .. code-block:: console
 130
 131    $ man -l draft/man3/strptime.3
 132
 133 翻訳状況の確認
 134 --------------
 135
 136 ページ毎の翻訳状況
 137 ~~~~~~~~~~~~~~~~~~
 138
 139 上記の draft page の生成の際に、翻訳状況のページ untrans.html が更新されます。
 140 このページを表示すると、ページ毎の翻訳状況が確認できます。
 141
 142 .. code-block:: console
 143
 144    w3m untrans.html
 145
 146 PO ファイル単位の翻訳状況
 147 ~~~~~~~~~~~~~~~~~~~~~~~~~
 148
 149 PO ファイル毎の翻訳状況も表示できます。
 150
 151 .. code-block:: console
 152
 153    make postats
 154
 155 未翻訳項目がある PO ファイルのみを表示することもできます。
 156
 157 .. code-block:: console
 158
 159    make untrans-postats
 160
 161 レビュー
 162 --------
 163
 164 JM ML に翻訳を投稿する場合は、以下のファイルを投稿して下さい。
 165
 166 * ja.po から生成された draft page
 167 * 翻訳した ja.po ファイルの git diff
 168   (または ja.po ファイルそのもの)
 169
 170 ja.po の diff は以下のコマンドで取得できます。 time の ja.po を翻訳した場合。
 171
 172 .. code-block:: console
 173
 174    git diff po4a/time/po/ja.po
 175
 176 .. note::
 177
 178    レビュー方法は改善の余地がいろいろあると思います。
 179    たとえば、プルリクエストを使うなど。
 180
 181 リリース
 182 --------
 183
 184 まとめてリリースを行う場合の手順です。
 185 通常は JM ML でレビューを行います。
 186
 187 ``make release`` を実行すると、以下を行います。
 188
 189 * draft page を release フォルダにコピー
 190 * translation_list を更新し、 PO ファイルで翻訳率が 100% になっているページのステータスを「☆」
 191   リリース済に変更します。
 192
 193 更新後は通常のリリース手順と同じです。
 194
 195 * release ファイルを git add → git commit
 196 * (必要に応じて) www/index.m4, www/news/index.m4 を更新