Vim ヘルプの日本語翻訳プロジェクトに contribute するために必要な技術
何か OSS に貢献したいと思っていた私が、Vim help を翻訳するために使った技術を紹介したいと思います。
（初心者向けの記事です）
これらの技術さえ覚えれば、誰でも OSS にコントリビュートできる！
まずはドキュメントをしっかり読む
Vim help の翻訳作業にあたっては、その作業手順や注意事項に対して、非常に丁寧な解説が、有志の方によって準備されています。
まずは、これらの作業手順や注意事項に、しっかりと目を通しましょう。
翻訳するドキュメントを宣言する （作業の重複を避ける）
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 に以下のように追記しました。
" vim-plug" https://github.com/junegunn/vim-plugif 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
endifcall 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/Guidehi Ignore ctermfg=red" autofmtの設定例set formatexpr=autofmt#japanese#formatexpr() " kaoriya版では設定済み
let autofmt_allow_over_tw=1 " 全角文字がぶら下がりで1カラムはみ出すのを許可
" command gq to format by autofmt" 以下のいずれかで、はみ出た部分の色を変える。synmatch Error /\%>79v.*/setcc=+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 できることがわかりました！（後、ほんのちょっと英語）