Markdown ファイルをコピーして翻訳するときの問題点
Markdown ドキュメントを多言語対応するには、普通、言語ごとに Markdown ファイルを用意します。たとえば、README.md を元にして日本語の README_ja.md、中国語の README_zh.md を作成するといったやり方で、最初に書いたドキュメントを元にそれぞれの翻訳ドキュメントを作成します。ところが、このやり方で翻訳作業を進めると、次のような問題があります。
- 翻訳ドキュメントの更新が難しい
- ドキュメントに無用の重複が生じる
- 元の文と翻訳文の比較が難しい
それぞれの問題点について少し説明します。
翻訳ドキュメントの更新が難しい
翻訳ドキュメントが古くなる問題はいろいろなライブラリのドキュメントで起きています。翻訳ドキュメントの内容が英語の最新版ドキュメントよりも古いバージョンのものになると、ドキュメントとして役に立たないだけでなく無用な誤解を生んでしまいます。翻訳ドキュメントを読んでいるうちに翻訳が古いバージョンのものあることに気がついて、原文を読まざるをえなくなり、結果的に余計遠回りになるといったことは、英語ネイティブでない人には誰でも経験があると思います。
また、たいていは役割分担がなされていて、元言語のドキュメントを書く人とそれを翻訳する人は違っています。その場合、元ドキュメントを更新したら翻訳する人にそのことを伝えなくてはなりません。翻訳する人が更新箇所を知るには Git の差分を見ることになりますが、複数のコミットやプルリクエストにまたがってドキュメントが更新されていると、更新すべき文を探すのも一苦労です。
ドキュメントに無用の重複が生じる
一般的に、プログラマは重複を嫌います。DRY (Don’t repeat yourself) の原則が語っているように、無用の重複があると変更が困難になり、メンテナビリティが下がります。
翻訳ドキュメントを書く素朴な手順は、次のようなものでしょう。
- 元ドキュメント
README.mdをコピーして翻訳ドキュメントREADME_ja.mdを作る - 翻訳ドキュメント
README_ja.mdのテキストを翻訳文に一文ずつ置き換える
これは DRY の原則に違反しています。このやり方では、ドキュメントに無用の重複が生じます。その一番大きなものがコードブロックです。ライブラリのドキュメントにはサンプルコードなどが書かれたコードブロックが多用されますが、ほとんどの場合、コードブロックは翻訳不要です。翻訳者はコードブロックには手を付けずに説明文だけを翻訳しますが、その結果、コードブロックは無用の重複として残ることになります。
想像してみましょう。元ドキュメント README.md のサンプルコードにタイポが紛れていることが発覚したら、README.mdだけでなく、README_ja.md と README_zh.md それぞれのサンプルコードを修正して回らなくてはなりません。
元の文と翻訳文の比較が難しい
翻訳ドキュメントが完成したとして、正しく翻訳できているかどうかを確認するにはどうすればいいでしょうか。翻訳ドキュメントと元ドキュメントの 2 ファイルをエディタで開いて並べ、見比べることになります。これでは効率よく翻訳の正しさをチェックできません。
Inalz による解決
要約すると、以上の問題は翻訳ドキュメントのメンテナンスが難しいということです。それを解決する Inalz のアプローチは、元ドキュメントと翻訳ドキュメントの間に中間ファイルを用意するというものです。
はじめに元ドキュメント README.md があります。そして、原文と翻訳文をマッピングするための中間ファイルが README.locale.yml で、Locale ファイルといいます。Locale ファイルは YAML で書かれ、シンプルに原文と翻訳文が一文ずつ並べられます。Locale ファイルで翻訳作業を行い、Locale ファイルから翻訳ドキュメント README_ja.md と README_zh.md を出力します。
Locale ファイルの特徴は次のとおりです。
- 元ドキュメントが更新されると、対象の翻訳文に
outdatedのラベルが自動で付く- そのため、更新すべき文がすぐにわかる
- コードブロックは翻訳対象とせず、Locale ファイルに含めない
- そのため、無用の重複を避けられる
- 原文と翻訳文が一文ずつ並ぶ
- そのため、翻訳作業と確認が容易である
また、中間ファイルを置くことで、ドキュメント作成の役割分担が明確になります。
- 元ドキュメントを書く人は翻訳のことを気にせず Markdown で自由に書ける
- 翻訳する人は元ドキュメントの構造を気にせず一文ずつの翻訳に集中できる
いわゆる関心の分離です。これが Inalz による解決です。