Vim ヘルプの日本語翻訳プロジェクトに contribute するために必要な技術

何か OSS に貢献したいと思っていた私が、Vim help を翻訳するために使った技術を紹介したいと思います。
（初心者向けの記事です）

これらの技術さえ覚えれば、誰でも OSS にコントリビュートできる！

まずはドキュメントをしっかり読む

Vim help の翻訳作業にあたっては、その作業手順や注意事項に対して、非常に丁寧な解説が、有志の方によって準備されています。
まずは、これらの作業手順や注意事項に、しっかりと目を通しましょう。

Vim 付属のヘルプを日本語に翻訳するためのプロジェクト

必読ドキュメント（作業手順等）

翻訳するドキュメントを宣言する（作業の重複を避ける）

2019/12/21 現在、以下の issue において、未翻訳ファイル情報の一覧が、有志の方によって提供されています。
また、作業が重複しないように、翻訳すると決めたファイルをここで宣言しましょう。

未翻訳ファイル情報を貼り付けたり、「今からこのファイルを翻訳するぜ」と意思表示する場所 (1)

今回私は、 editing.txt の修正を行うことに決めました。

fork and git clone

まずは、プロジェクトのレポジトリを fork します。
github のページから、自分の github アカウントへ、 vim-jp/vimdoc-ja-working を fork します。

その後、自分のローカル環境に、fork したレポジトリを clone します。
例えば、私のアカウントだと、

git clone https://github.com/hnishi/vimdoc-ja-working.git

作業環境の整備

基本的には、以下に記載されている内容を行います。

Guide · vim-jp/vimdoc-ja-working Wiki · GitHub

私は、.vimrc に以下のように追記しました。

.vimrc

" vim-plug
" https://github.com/junegunn/vim-plug
if empty(glob('~/.vim/autoload/plug.vim'))
  silent !curl -fLo ~/.vim/autoload/plug.vim --create-dirs
    \ https://raw.githubusercontent.com/junegunn/vim-plug/master/plug.vim
  autocmd VimEnter * PlugInstall --sync | source $MYVIMRC
endif

call plug#begin()
Plug 'vim-jp/autofmt'
call plug#end()
" do :PlugInstall to install plugins

" for translate vimdoc
" https://github.com/vim-jp/vimdoc-ja-working/wiki/Guide
hi Ignore ctermfg=red
" autofmtの設定例
set formatexpr=autofmt#japanese#formatexpr()  " kaoriya版では設定済み
let autofmt_allow_over_tw=1                   " 全角文字がぶら下がりで1カラムはみ出すのを許可
" command gq to format by autofmt
" 以下のいずれかで、はみ出た部分の色を変える。
syn match Error /\%>79v.*/
set cc=+1
" ファイル形式
" 文字コードは UTF-8
" 改行文字は UNIX 形式(\n)
set modifiable
set fileencoding=utf-8 fileformat=unix

はじめに、 autofmt というフォーマットするためのプラグインを導入するために、 vim-plug という vim plugin マネージャーをインストールしています。
以下のように .vimrc に書いておくことで、 ~/.vim/autoload/plug.vim が存在しない場合に、自動でインストールされるようになっています。

if empty(glob('~/.vim/autoload/plug.vim'))
  silent !curl -fLo ~/.vim/autoload/plug.vim --create-dirs
    \ https://raw.githubusercontent.com/junegunn/vim-plug/master/plug.vim
  autocmd VimEnter * PlugInstall --sync | source $MYVIMRC
endif

以下で、autofmt を vim-plug で install するように設定しています。
後からプラグインを追加する場合は、.vimrc を更新して、 :PlugInstall でインストールできます。

call plug#begin()
Plug 'vim-jp/autofmt'
call plug#end()

set formatexpr=autofmt#japanese#formatexpr()
let autofmt_allow_over_tw=1

autofmt が入った状態で、gq コマンドを vim で実行すると、78文字目で簡単に改行できるようになります（後述）。

また、注意点として、vim-plug でプラグインをインストールする際に、以下の設定が原因でエラーが出ました。

set fileencoding=utf-8 fileformat=unix

エラーメッセージ

Error detected while processing /root/.vimrc:
line  121:
E21: Cannot make changes, 'modifiable' is off: fileencoding=utf-8
Press ENTER or type command to continue

modifiable が off になっていたので、以下のように on になるように .vimrc に追記しました。

set modifiable

その他の設定は、Guide に記載の通りです。

作業用の branch を作る

作業用のブランチを作って、そこで翻訳作業を行います。
例えば、

git checkout -b update-editing

英語版ヘルプの update 差分を確認する

作業手順にあるように、まずは、vim 本体の英語 txt ファイルを、vimdoc-ja-working/en/ にコピーします。
git diff で、差分を確認することができます。

対応する日本語ドキュメントを修正する

vimdoc-ja-working/doc/editing.jax

のように、英語に対応する日本語のファイルがあるので、英語版の差分を見ながら、変更箇所を修正します。

ちなみに、.jax という拡張子は、単にヘルプの言語の種類を示しているようです。

日本語に翻訳されたvimエディタのヘルプをインストールして使用する。 — 名無しのvim使い

今回、私が担当した editing.txt の修正は、

MS-DOS, Win32 and OS/2 --> Win32

と置換するだけの簡単な修正でした。
ただ、置換すると１行あたりの文字数が変わってしまうため、改行する位置を変更する必要がありました。

(MS-DOS、OS/2 と Win32 での既定値) では、<CR><NL> と <NL> の両方が <EOL> と解
釈される。 Note DOS 形式でファイルを保存するときには、<NL> 1 個ごとに対して
<CR> が追加されることに注意。|file-read| も参照。

これを修正すると、１行あたりの文字数が変わリます。

autofmt を使えば、(Win32 での既定値) ではから始まる行にカーソルがある状態で、gq2j と実行することで、以下のように１行あたり78文字までになるように、自動でフォーマットしてくれます。

(Win32 での既定値) では、<CR><NL> と <NL> の両方が <EOL> と解 釈される。 Note
DOS 形式でファイルを保存するときには、<NL> 1 個ごとに対して <CR> が追加されるこ
とに注意。|file-read| も参照。

修正したファイルをブラウザでプレビューする

レポジトリのルートディレクトリで、

make html

を実行すると、
例えば、 target/html/doc/editing.html のように、html が生成されます。
ただ、全ての help の html を生成するので時間はかかります。
この、html をダブルクリックで、ブラウザで修正したファイルを確認することができます。

もしくは、.jax ファイルを vim で開いて

:TOhtml|wq editing.html|q

を実行することで、カレントディレクトリに editing.html が作成されます。

ただし、この方法だと、ハイパーリンクなどは、ちゃんと処理されません。

git commit and git push

修正した変更を commit します。
例えば、

git commit -a -m "update editing.{txt,jax}"

フォークしたレポジトリに、現在のブランチを push します。

git push origin update-editing

PR の作成

github 上のページから、プルリクエスト (PR) を作成します。
先ほど push したブランチを、vim-jp/vimdoc-ja-working の master に対して、PR を作成します。

Review を受ける

この後、レビューを受けて、問題なければマージされます。

まとめ

Vim help の翻訳を行ってみました
出来るだけ初心者でもわかるように、手順を整理してみました
git, vim の知識があれば、誰でも Vim help の翻訳に Contribute できることがわかりました！（後、ほんのちょっと英語）

Vim ヘルプの日本語翻訳プロジェクトにコントリビュートするために必要な技術