(split) LDP: Update README.JM

[linuxjm/LDP_man-pages.git] / README.JM.org

* How to Translate

LDP man-pages では、翻訳に po4a を利用しています。

roff ファイルと po4a ファイルの変換には、LDP man-pages のフランス語翻訳チームが
公開している perkamon を利用しています。
perkamon を git submodule として利用しているため、手順が少し複雑になっています。

** 前準備

git repository の top directory で以下のコマンドを実行します。

#+BEGIN_EXAMPLE
cd $JM_REPO_TOP
git submodule update --init
#+END_EXAMPLE

po4a 環境を用意します。

#+BEGIN_EXAMPLE
cd manual/LDP_man-pages
make jm-setup
#+END_EXAMPLE

これで po4a で作業して draft に反映する準備が整いました。

** 翻訳と draft への変換

*** ja.po と man page の関係

一つの po ファイルは、 LDP\_man-pages の複数の man page に対応しています。
man page に対応する po ファイルを特定するには、以下のようにします。

#+BEGIN_EXAMPLE
$ grep -l strptime.3 perkamon/po4a/*/*.cfg
perkamon/po4a/time/time.cfg
#+END_EXAMPLE

上記の場合、strptime.3 が含まれる po ファイル (ja.po) は time 以下にあります。
po4a/time/po/ja.po を翻訳することになります。

#+BEGIN_EXAMPLE
$ find po4a/time/ -type f
po4a/time/po/ja.po
po4a/time/po/time.pot
#+END_EXAMPLE

*** 翻訳

上記で特定した ja.po を翻訳します。

エディタは po ファイルに対応しているものが便利です。
- Emacs を使っていれば Emacs の po-mode が便利です。
- gedit も PO ファイルをきれいに色付けしてくれるので、作業しやすいと思います。

*** draft page の生成

ja.po から draft を生成するには以下のいずれかを実行します (どちらも同じです)。
更新を行った PO ファイルのみが変換されます。

#+BEGIN_EXAMPLE
make
make translate
#+END_EXAMPLE

初めて実行する際には、全ての ja.po が変換対象になるので、時間がかかります。
どのファイルが更新されたかは git status で確認して下さい。

#+BEGIN_EXAMPLE
git status .
#+END_EXAMPLE

デフォルトでは、翻訳率 80% 以上のページが生成されます。
80% にしている理由は、ある程度日本語混じりの draft page を見ながら翻訳する方が
全体の文脈をつかみやすいためです。全部翻訳できたかは、下記の「翻訳状況の確認」
の方法で確認できるので、翻訳率 100% を閾値にする必要はないと考えています。

*** 翻訳状況の確認

- *ページ毎の翻訳状況* :
  上記の draft page の生成の際に、翻訳状況のページ untrans.html が更新されます。
  このページを表示すると、ページ毎の翻訳状況が確認できます。

  #+BEGIN_EXAMPLE
w3m untrans.html
#+END_EXAMPLE

- *PO ファイル単位の翻訳状況* :
  PO ファイル毎の翻訳状況も表示できます。

  #+BEGIN_EXAMPLE
make postats
#+END_EXAMPLE

  未翻訳項目がある PO ファイルのみを表示することもできます。

  #+BEGIN_EXAMPLE
make untrans-postats
#+END_EXAMPLE

** レビュー

JM ML に翻訳を投稿する場合は、以下のファイルを投稿して下さい。

- ja.po から生成された draft page
- 翻訳した ja.po ファイルの git diff
  (または ja.po ファイルそのもの)

ja.po の diff は以下のコマンドで取得できます。 time の ja.po を翻訳した場合。

#+BEGIN_EXAMPLE
git diff po4a/time/po/ja.po
#+END_EXAMPLE

** リリース

まとめてリリースを行う場合の手順です。
通常は JM ML でレビューを行います。

make release を実行すると、以下を行います。
- draft page を release フォルダにコピー
- translation_list を更新し、 PO ファイルで翻訳率が 100% になっているページのステータスを「☆」
  リリース済に変更します。

更新後は通常のリリース手順と同じです。
 * release ファイルを git add -u → git commit
 * (必要に応じて) www/index.m4, www/news/index.m4 を更新

* How to update original

Git Repo 以下はきれいな状態にした状態で始めること。

1. perkamon を更新する

   #+BEGIN_EXAMPLE
  cd perkamon
  git remote add upstream git://gitorious.org/perkamon/man-pages.git
  git remote update
  git checkout master
  git merge upstream/master
  git push origin
  cd -
#+END_EXAMPLE

   現状 JM 用の perkamon は amotoki が管理する GitHub Repository
   https://github.com/amotoki/perkamon.git にあります。
   Commit 権が必要であれば Collaborator に登録しますので、連絡下さい。

2. perkamon 作業ディレクトリに最新版に対応した展開する

   #+BEGIN_EXAMPLE
make clean-setup
make jm-setup
#+END_EXAMPLE

   以下の作業が行われる。

   - 最新版の man-pages の tarball が perkamon/ 直下にダウンロードされる。
   - tarball が perkamon/man-pages ディレクトリに展開される。
   - po4a 作業用の source lang が build/C として用意される。
     - 実際にコンテンツがあるファイルが build/C/man? 以下に man-pages 以下から
       コピーされる。
     - po4a-fixes.patch がある場合には、build/C/ 以下のファイルに適用される。
     - リンクファイルは build/C/link に一覧が作成される。

3. original 以下にコピーする

   #+BEGIN_EXAMPLE
cd perkamon/man-pages
../../../../admin/JM-orig-upd.sh ../../original
cp README man-pages-* Changes* ../../original
cd -
#+END_EXAMPLE

4. COLOPHON 以下を削除する。

   translation\_list を更新する際に、変更点のみを抽出するために行う。
   COLOPHON 部分はリリース毎にバージョン番号が更新されてしまうので、
   original に登録する際には、この節を削除しておく。

   #+BEGIN_EXAMPLE
cd original
sed -e 's/\^\\\.SH /^\\.S[Hh] /' ../perkamon/man-pages/scripts/remove_COLOPHON.sh
sh ../perkamon/man-pages/scripts/remove_COLOPHON.sh man?/*.[1-8]
#+END_EXAMPLE

5. original 以下を git で stage する。

   original 以下で作業する。基本的に original 以下の変更は全部取り込む

   #+BEGIN_EXAMPLE
git add -u
git add .
#+END_EXAMPLE

6. translation\_list の更新

   #+BEGIN_EXAMPLE
cd ..
(LDP_man-pages の直下に移動する)
git status original | ../../admin/git2upd > upd.txt
vi upd.txt
(不要な行の削除を行う)
../../admin/upd_tl.perl translation_list upd.txt 3.XX
mv translation_list.3.XX translation_list
#+END_EXAMPLE

7. Git commit

   #+BEGIN_EXAMPLE
git add translation_list
git commit -m "LDP: Update original to LDP v3.XX"
#+END_EXAMPLE

8. POT の更新

   #+BEGIN_EXAMPLE
cd perkamon
make print-new-files
(何か表示されたら、po4a/*/*.cfg に追加)
make disable-removed
(何かないか確認)
git status
(更新があれば git commit)

cd ..
make FLAGS="--no-translations -v --force"
(これで POT と ja.po が更新される。
 タイムスタンプを気にしなくてよいので --force を付けた方がよい。)
git add -u po4a/
git commit -m "LDP: Update POT and ja.po to LDP v3.XX"
#+END_EXAMPLE

   この時点で draft, stats, untrans.html release も更新されている。

9. 単純な fuzzy の更新

   COLOPHON が更新されているので、fuzzy が少なくとも一つできる。
   ja.po で fuzzy を探してバージョンを更新する。

   #+BEGIN_EXAMPLE
make
git add -u po4a/ stats/ untrans.html
git commit -m "LDP: Update the version to 3.XX in PO files"

git add draft/
git commit -m "LDP: Update draft pages based on LDP 3.XX release"

make release
git add release/
git add -u translation_list
git commit -m "LDP: Update release pages based on LDP 3.XX release"
#+END_EXAMPLE