英語圏のオープンソースプロジェクトにおける翻訳ドキュメントの問題点とその解決のための一方策

(追記：2014-02-17) togglateの仕様を変更しましたので、最新情報については下記記事を参照してください。

英語圏のオープンソースプロジェクトにおける翻訳ドキュメントの問題点とその解決のための一方策（仕切り直し版）

オープンソースプロジェクトの大半は英語ベースです。素晴らしいプロジェクトには大概、素晴らしいドキュメントが付属しており、そのドキュメントを読むことがそのプロジェクトに係る技術を理解する第一歩になります。しかし、英語を母国語としない私たちにとって、英語のドキュメントを通して技術を理解することには一定の困難と苦痛が伴います。

このような背景からいくつかのプロジェクトでは、多言語によるドキュメントをそのプロジェクトの一部として含んでいるものがあります。また、それとは別に有志により翻訳が別リソースとして公開されているケースもあります。このような翻訳ドキュメントの存在が非英語圏の技術者の役に立つことは言うまでもなく、そのプロジェクトの普及のためにも有益であるに違いありません。

翻訳ドキュメントの問題点

しかし、その一方で、翻訳ドキュメントには次のような問題が内在しています。

プロジェクトのコントリビュータは、通常、翻訳ドキュメントの内容を理解できないので、その管理および質の担保は、その翻訳者らに依存することになる。

翻訳ドキュメントの利用者において、翻訳上のミスや不適切さなどから原文を確認したいことがあるが、そのために原文の対応箇所を探さなければならない。

オリジナルドキュメント（原文）に変更が生じている場合、翻訳ドキュメントにおける追随の程度を把握するのに手数を要する。

実際、私がSinatraにおける日本語READMEをアップデートしたときにこれらの問題が顕在化しました。

英語圏のオープンソースプロジェクトに貢献する最も簡単な方法またはsinatra/README.jp.mdまたは彼はなぜ私を愛するようになったか

解決のための一方策

これらの問題は、要するに原文と訳文の対応関係が保証されていないことに起因します。そこで、以下のような対応策を考えてみました。なお、ここでの前提として、オリジナルドキュメントおよび翻訳ドキュメントはMarkdown記法で書かれ、HTML形式に変換されて読まれるものとしています。

原文のすべてを翻訳ドキュメントに含める。

訳文は原文のセンテンスごとにそれに付随して書く。

原文をセンテンスごとに特別なタグで囲み、このブロックを表示・非表示切り替え可能にする。

原文の変更に伴う翻訳ドキュメントの更新を行う場合は、その対応原文センテンスも併せて更新する。

このようにして、翻訳ドキュメント内に原文を埋め込むことで次のような効果が期待できます。

原文と訳文のセンテンスごとの対応関係が明確になり、メンテナンス性が上がる。

オリジナルドキュメントと翻訳ドキュメント内の原文との差分を見ることで、翻訳文が読めなくても、翻訳ドキュメントがオリジナルの更新に追随しているかがわかる。

翻訳ドキュメントの利用者が容易に原文を確認できる一方で、その原文は非表示にできるので邪魔にならない。

チュートリアル

上記方針に従った翻訳ドキュメントの作成プロセスを、簡単な例で試してみます。

準備

ここではこの目的のために作成したtogglateというツールと、Github社謹製github-markdown(gfm)というツールを使います。

github-markdownは、Github向けMarkdown(GFM)ファイルをHTMLファイルに変換するツールです（ GitHub Flavored Markdown）。

togglateはオリジナルドキュメントから翻訳ドキュメントのベースとなるドキュメントを生成するツールです。このツールは、センテンスごとに特別のタグで囲まれた原文をコピーし、これをトグルするためのコードを挿入します。デフォルトでgithub-markdownに合わせた仕様になっています。

翻訳ドキュメントの生成プロセスを図にすると以下のようになります。

togglate noshadow

togglate、github-markdownともにgem化されているので、インストールは簡単です。

% gem install togglate
% gem install github-markdown

これによりtogglateというコマンドとgfmというコマンドが使えるようになりますが、gfmは以下のようにして手動でパスを通す必要があります。

% ln -s .rbenv/versions/2.1.0/lib/ruby/gems/2.1.0/gems/github-markdown-0.6.4/bin/gfm /usr/local/bin

オリジナルドキュメント

次のような英語で書かれたmarkdownファイル(README.md)があると仮定します。

## AwesomeTool

AwesomeTools is a DSL for quickly creating awesome tools in Ruby.

```ruby
# mytool.rb
require 'awesome_tool'

awesome 'nhk' do |name|
  'You are awesome, #{name}!'
end
```

install the gem:

    gem install awesome_tool

And run with:

    awesome nhk 'charlie'

Turn on the TV, select NHK.
You will see `You are awesome, charlie!` message on the screen.

翻訳ベースドキュメントの生成

togglate createコマンドで、README.mdから翻訳のベースとなるドキュメント(README.ja.md)を生成します。

% togglate create README.md > README.ja.md

これにより次のようなREADME.ja.mdが生成されます。

[translation here]
```original
## AwesomeTool
```

[translation here]
```original
AwesomeTools is a DSL for quickly creating awesome tools in Ruby.
```

```ruby
# mytool.rb
require 'awesome_tool'

awesome 'nhk' do |name|
  'You are awesome, #{name}!'
end
```

[translation here]
```original
install the gem:
```

    gem install awesome_tool

[translation here]
```original
And run with:
```

    awesome nhk 'charlie'

[translation here]
```original
Turn on the TV, select NHK.
You will see `You are awesome, charlie!` message on the screen.
```


<script src="http://code.jquery.com/jquery-1.11.0.min.js"></script>
<script>
function createToggleLinks(target, showText, hideText) {
var link = "<span><a href='#' onclick='javascript:return false;' class='toggleLink'>" + showText + "</a></span>";
target.hide().prev().append(link);
$('.toggleLink').click(
  function() {
    if ($(this).text()==showText) {
     $(this).parent().parent().next(target).slideDown(200);
     $(this).text(hideText);
    } else {
      $(this).parent().parent().next(target).slideUp(200);
      $(this).text(showText);
    };
  });
}
var element = $("pre[lang='original']");
createToggleLinks(element, "*", "hide");
</script>

ポイントは次の3点です。

原文の各センテンスをoriginal, で囲み、直前に[translation here]というマークを挿入

コードブロックは原文のまま挿入

末尾に原文ブロックをトグルするJavaScriptコードを挿入

翻訳作業

[translation here]のマークの箇所に、その直下の原文に対応する訳文を入れます。訳が不要な箇所はoriginalブロックを削除します¹。

## AwesomeTool

AwesomeToolは、Rubyで手早くすごいツールを作るためのDSLです。
```original
AwesomeTools is a DSL for quickly creating awesome tools in Ruby.
```

```ruby
# mytool.rb
require 'awesome_tool'

awesome 'nhk' do |name|
  'You are awesome, #{name}!'
end
```

Gemをインストールします。
```original
install the gem:
```

    gem install awesome_tool

そして、実行します。
```original
And run with:
```

    awesome nhk 'charlie'

テレビを付けて、NHKを選曲します。
`You are awesome, charlie!`というメッセージをスクリーン上で確認できるでしょう。
```original
Turn on the TV, select NHK.
You will see `You are awesome, charlie!` message on the screen.
```

\ コードは省略

HTML変換

gfmコマンドを使って翻訳が済んだREADME.ja.mdからHTMLファイル(README.ja.html)を生成します。

% gfm README.ja.md > README.ja.html

次のREADME.ja.htmlファイルが生成されます。

<h2>AwesomeTool</h2>

<p>AwesomeToolは、Rubyで手早くすごいツールを作るためのDSLです。</p>

<pre lang="original"><code>AwesomeTools is a DSL for quickly creating awesome tools in Ruby.
</code></pre>

<pre lang="ruby"><code># mytool.rb
require &#39;awesome_tool&#39;

awesome &#39;nhk&#39; do |name|
  &#39;You are awesome, #{name}!&#39;
end
</code></pre>

<p>Gemをインストールします。</p>

<pre lang="original"><code>install the gem:
</code></pre>

<pre><code>gem install awesome_tool
</code></pre>

<p>そして、実行します。</p>

<pre lang="original"><code>And run with:
</code></pre>

<pre><code>awesome nhk &#39;charlie&#39;
</code></pre>

<p>テレビを付けて、NHKを選曲します。<br>
<code>You are awesome, charlie!</code>というメッセージをスクリーン上で確認できるでしょう。</p>

<pre lang="original"><code>Turn on the TV, select NHK.
You will see `You are awesome, charlie!` message on the screen.
</code></pre>

これをブラウザで表示すると次のように見えます。文末のアスタリスク*をクリックしてみてください。原文が表示されます。

AwesomeTool

AwesomeToolは、Rubyで手早くすごいツールを作るためのDSLです。

AwesomeTools is a DSL for quickly creating awesome tools in Ruby.

# mytool.rb
require 'awesome_tool'

awesome 'nhk' do |name|
  'You are awesome, #{name}!'
end

Gemをインストールします。

install the gem:

gem install awesome_tool

そして、実行します。

And run with:

awesome nhk 'charlie'

テレビを付けて、NHKを選曲します。
You are awesome, charlie!というメッセージをスクリーン上で確認できるでしょう。

Turn on the TV, select NHK.
You will see `You are awesome, charlie!` message on the screen.

オリジナルドキュメントと翻訳ドキュメントの差分

diffを使って、オリジナルドキュメントと翻訳ドキュメントの差分を取ってみます。

% diff -u README.md README.ja.md

出力です。

--- README.md	2014-02-10 21:14:49.000000000 +0900
+++ README.ja.md	2014-02-11 08:41:18.000000000 +0900
@@ -1,6 +1,9 @@
 ## AwesomeTool
 
+AwesomeToolは、Rubyで手早くすごいツールを作るためのDSLです。
+```original
 AwesomeTools is a DSL for quickly creating awesome tools in Ruby.
+```
 
 ```ruby
 # mytool.rb
@@ -11,14 +14,44 @@
 end
 ```
 
+Gemをインストールします。
+```original
 install the gem:
+```
 
     gem install awesome_tool
 
+そして、実行します。
+```original
 And run with:
+```
 
     awesome nhk 'charlie'
 
+テレビを付けて、NHKを選曲します。
+`You are awesome, charlie!`というメッセージをスクリーン上で確認できるでしょう。
+```original
 Turn on the TV, select NHK.
 You will see `You are awesome, charlie!` message on the screen.
+```
+
 
+<script src="http://code.jquery.com/jquery-1.11.0.min.js"></script>
+<script>
+function createToggleLinks(target, showText, hideText) {
[コードの差分は省略]

オリジナルに対し追加操作だけが行われたことが分かります。

オリジナルドキュメントの更新

AwesomeToolのAPIが変わりオリジナルドキュメントが次のように更新されたとします。

diff --git a/README.md b/README.md
index 07da30d..2a60341 100644
--- a/README.md
+++ b/README.md
@@ -9,6 +9,10 @@ require 'awesome_tool'
 awesome 'nhk' do |name|
   'You are awesome, #{name}!'
 end
+
+awesome do |name|
+  call :nhk
+end
 ```
 
 install the gem:
@@ -21,3 +25,9 @@ And run with:
 
 Turn on the TV, select NHK.
 You will see `You are awesome, charlie!` message on the screen.
+
+Alternatively, you can say:
+
+    awesome 'charlie'
+
+Look at the sky, you will see the message with clouds.

コードの一部改変と機能説明の追記が行われました。

翻訳ドキュメントの更新

翻訳ドキュメントがオリジナルに追随しているかみるために、更新後のオリジナルと翻訳ドキュメントの差分を取ります。

% diff -u README.md README.ja.md

出力です。

--- README.md	2014-02-11 08:52:01.000000000 +0900
+++ README.ja.md	2014-02-11 08:41:18.000000000 +0900
@@ -1,6 +1,9 @@
 ## AwesomeTool
 
+AwesomeToolは、Rubyで手早くすごいツールを作るためのDSLです。
+```original
 AwesomeTools is a DSL for quickly creating awesome tools in Ruby.
+```
 
 ```ruby
 # mytool.rb
@@ -9,25 +12,46 @@
 awesome 'nhk' do |name|
   'You are awesome, #{name}!'
 end
-
-awesome do |name|
-  call :nhk
-end
 ```
 
+Gemをインストールします。
+```original
 install the gem:
+```
 
     gem install awesome_tool
 
+そして、実行します。
+```original
 And run with:
+```
 
     awesome nhk 'charlie'
 
+テレビを付けて、NHKを選曲します。
+`You are awesome, charlie!`というメッセージをスクリーン上で確認できるでしょう。
+```original
 Turn on the TV, select NHK.
 You will see `You are awesome, charlie!` message on the screen.
+```
 
-Alternatively, you can say:
-
-    awesome 'charlie'
 
-Look at the sky, you will see the message with clouds.
+<script src="http://code.jquery.com/jquery-1.11.0.min.js"></script>
+<script>
+function createToggleLinks(target, showText, hideText) {
[コードの差分は省略]

追随していない部分があることが分かりました（赤字部分）。

それらの箇所を翻訳ドキュメント側にコピーし、対応訳を書きます。結果をdiffで確認します。

--- README.md	2014-02-11 09:09:44.000000000 +0900
+++ README.ja.md	2014-02-11 09:09:13.000000000 +0900
@@ -1,6 +1,9 @@
 ## AwesomeTool
 
+AwesomeToolは、Rubyで手早くすごいツールを作るためのDSLです。
+```original
 AwesomeTools is a DSL for quickly creating awesome tools in Ruby.
+```
 
 ```ruby
 # mytool.rb
@@ -15,19 +18,55 @@
 end
 ```
 
+Gemをインストールします。
+```original
 install the gem:
+```
 
     gem install awesome_tool
 
+そして、実行します。
+```original
 And run with:
+```
 
     awesome nhk 'charlie'
 
+テレビを付けて、NHKを選曲します。
+`You are awesome, charlie!`というメッセージをスクリーン上で確認できるでしょう。
+```original
 Turn on the TV, select NHK.
 You will see `You are awesome, charlie!` message on the screen.
+```
 
+代わりに、次のように言ってもいいです。
+```original
 Alternatively, you can say:
+```
 
     awesome 'charlie'
 
+空を見上げれば、雲で作られた先のメッセージが見えるでしょう。
+```original
 Look at the sky, you will see the message with clouds.
+```
+
+<script src="http://code.jquery.com/jquery-1.11.0.min.js"></script>
+<script>
+function createToggleLinks(target, showText, hideText) {
[コードの差分は省略]

赤字が消え、翻訳ドキュメントがオリジナルに追随していることが分かります。

更新後の翻訳ドキュメントをWebに表示してみます。

AwesomeTool

AwesomeToolは、Rubyで手早くすごいツールを作るためのDSLです。

AwesomeTools is a DSL for quickly creating awesome tools in Ruby.

# mytool.rb
require 'awesome_tool'

awesome 'nhk' do |name|
  'You are awesome, #{name}!'
end

awesome do |name|
  call :nhk
end

Gemをインストールします。

install the gem:

gem install awesome_tool

そして、実行します。

And run with:

awesome nhk 'charlie'

テレビを付けて、NHKを選曲します。
You are awesome, charlie!というメッセージをスクリーン上で確認できるでしょう。

Turn on the TV, select NHK.
You will see `You are awesome, charlie!` message on the screen.

代わりに、次のように言ってもいいです。

Alternatively, you can say:

awesome 'charlie'

空を見上げれば、雲で作られた先のメッセージが見えるでしょう。

Look at the sky, you will see the message with clouds.

と、まあこんなものを考えたんですけど、どうでしょうか。

melborne/togglate

削除しないで残したほうがいいのかもしれません。 ↩

=== Ruby関連電子書籍100円〜で好評発売中！ ===

M’ELBORNE BOOKS

blog comments powered by Disqus

100円〜で好評発売中！
M'ELBORNE BOOKS