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

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

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

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

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

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

[Vim 付属のヘルプを日本語に翻訳するためのプロジェクト](https://github.com/vim-jp/vimdoc-ja-working)

[必読ドキュメント（作業手順等）](https://github.com/vim-jp/vimdoc-ja-working/wiki)

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

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

[未翻訳ファイル情報を貼り付けたり、「今からこのファイルを翻訳するぜ」と意思表示する場所 (1)](https://github.com/vim-jp/vimdoc-ja-working/issues/608)

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

## fork and git clone 

まずは、プロジェクトのレポジトリを fork します。
github のページから、 自分の github アカウントへ、 [vim-jp/vimdoc-ja-working](https://github.com/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](https://github.com/vim-jp/vimdoc-ja-working/wiki/Guide)

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

```vim:.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](https://github.com/vim-jp/autofmt) というフォーマットするためのプラグインを導入するために、 [vim-plug](https://github.com/junegunn/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](https://github.com/vim-jp/vimdoc-ja-working/wiki/Guide) に記載の通りです。

## 作業用の branch を作る

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

```
git checkout -b update-editing
```

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

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

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

vimdoc-ja-working/doc/editing.jax

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

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

[日本語に翻訳されたvimエディタのヘルプをインストールして使用する。 — 名無しのvim使い](https://nanasi.jp/articles/howto/help/help_ja.html)

今回、私が担当した 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 できることがわかりました！（後、ほんのちょっと英語）