多言語の技術レッスン集で、翻訳を英語の原本に合わせ続ける

## アプリのコードには触れず、レッスン・記事・翻訳だけを直す あなたが保守するのはコンテンツ専用のリポジトリであり、指導用レッスン、記事、およびそれらの翻訳を扱う。このコンテンツを描画する公開アプリケーションは別の場所にあり、このリポジトリには含まれない。あなたの仕事は文章、構成、メタデータであって、アプリケーションのコードではない。 守るべき範囲の境界は次のとおり。 - アプリケーションのソースコード、ビルドツール、実行時設定をここに追加しない。サイトの挙動を変える必要がある変更であれば、その旨を明示的に述べ、公開アプリケーション側で必要となる対応変更を説明する。ここで即興的に対応しない。 - コンテンツ自体を集計・報告する小さな保守スクリプト（たとえば翻訳ステータスレポート）は正当なものであり、置き換えるのではなく編集前に活用する。 - すべてのファイルは、後に人間の翻訳者が従うことになるものとして扱う。自分にとって都合がよくても翻訳ワークフローを壊す変更は、悪い変更である。 - 依頼が原典言語を対象としているのか翻訳を対象としているのか曖昧な場合は、書き始める前に確認する。推測を誤ると、後述する陳腐化追跡が黙って壊れる。 ## 言語ごとのフォルダをそろえ、先に英語の原本を直す このライブラリは、予測可能で対称的な構成を採る。レッスンファイルはレッスン用ディレクトリの下に置かれ、その下にISO言語コード名のフォルダ、さらにカテゴリーフォルダ、そしてドキュメント本体が続く。ブログ記事は単一の記事ディレクトリに置かれ、日付の接頭辞に続けてハイフン区切りのスラッグを付けた名前とする。これによりファイル名だけで時系列の順序が分かる。 各言語配下のカテゴリー集合は固定されており、全言語で同一である。一般的なカテゴリーは、基礎、中級、上級、ストレージ、テスト、データ処理、フレームワーク固有の資料、およびその他をまとめる分類である。ひとつの言語だけにカテゴリーを新設しない。追加するなら全言語に追加し、そうでなければどこにも追加しない。 ひとつの言語（通常は英語）が、信頼できる唯一の原典である。他のすべての言語ディレクトリは、その翻訳を保持する。 ここから導かれるルールは次のとおり。 - 実質的な変更はまず原典言語で行い、その後に翻訳へ反映する。新しい事実、例、セクションを翻訳だけに導入してはならない。 - 翻訳を単独で修正してよいのは、翻訳品質上の理由に限られる。すなわち誤訳、文法、体裁、ロケール慣習である。 - 翻訳に見つけた誤りが原典にも存在する場合は、原典を修正し、翻訳は後続作業として扱う。 ## 変更の大きさで版の番号を上げ、翻訳に同じ番号を写す すべてのドキュメントは、区切り線で終端される構造化されたメタデータブロックで始まる。このブロックは最低限、バージョン文字列、タイトル、そしてドキュメントを1〜2文で要約した短い抜粋を含む。記事形式の投稿はさらに、著者名、著者リンク、タグ、公開日を持つ。 バージョンフィールドは装飾ではなく、機械が読み取る値である。翻訳は、翻訳元となった原典ドキュメントのバージョンをそのまま複写する。ツールは各翻訳のバージョンを現在の原典バージョンと比較し、その翻訳が最新か、軽度に陳腐化しているか、深刻に陳腐化しているかを判定する。 原典のバージョンは、変更の規模に応じて上げる。 - メジャー: ドキュメントが大幅に書き直された。翻訳者は作業をやり直す必要がある。 - マイナー: 文、段落、例が追加または削除された。翻訳者は内容を確認し、差分を反映する必要がある。 - パッチ: 綴りや体裁の修正のみ。翻訳はそのまま利用できる。 対応する変更を伴わずにバージョンを上げてはならず、実質的な変更をバージョンを上げずに行ってもならない。どちらの誤りも陳腐化レポートの正確性を損なう。このレポートこそが、翻訳ライブラリの誠実さを保つ唯一の仕組みである。 翻訳を編集する際は、実際に新しい原典の内容へ追いつかせた場合に限り、そのバージョンを更新する。 ## 「私たち」の口調で、説明より先に例を見せる ロケール別ガイドが上書きしない限り、以下の規約をすべてのコンテンツに適用する。 - 包摂的な一人称複数を用いる。読者は講義を受ける生徒ではなく、あなたと並んで作業する協働者である。「〜しなければならない」という言い方が不自然にならない箇所では「私たち」を使う。 - まず見せ、次に説明する。実例が先にあり、その説明が後に続く。読者は対象について読む前に、対象そのものを目にする。 - 段落は短く保つ。情報が密になってきたら、長い段落にせず箇条書きや例示ブロックへ変換する。 - 能動態を用いる。堅苦しい非短縮形ではなく、短縮形を一貫して用いる。 - 絵文字は使わない。決まり文句、称賛のための埋め草、次の文を導くためだけに存在する文も書かない。 - 列挙の最後の項目の前にもカンマ（シリアルカンマ）を置く。 - 見出しレベル: 主要セクションは第2レベル見出し、下位セクションは第3レベル見出しとする。本文中に最上位レベルの見出しを置いてはならない。そのレベルはドキュメントタイトルのためのものである。 - すべての例示ブロックは言語識別子を宣言し、レンダラーが正しくハイライトできるようにする。 学びにつながらないものはすべて削る。長さは美徳ではない。翻訳者が忠実に再現できる短いドキュメントは、内容がぶれていく長いドキュメントより価値がある。 ## 各レッスンを、概要から例、関連する話の順に組む 指導用ドキュメントは、次の固定された物語構造に従う。 1. そのドキュメントが扱う内容の簡潔な概要。 2. 動機、すなわちなぜこれが重要なのかを、最大でも2〜3文で述べる。このセクションを膨らませない。埋め草が最もたまりやすい箇所である。 3. 中核となる内容。具体例を軸に進め、各例のあとに説明を続ける。 4. 外側とのつながり。この主題が、読者がすでに読んだ、あるいは次に読む関連資料とどう関係するか。 中核部分では、最も単純に使える事例からより複雑な変種へと順に並べ、用語はそれに依存する前に導入する。ドキュメントが明確に分離できる2つの主題を扱うまで膨らんだ場合は、放置して肥大化させるのではなく分割する。焦点の定まった2本のドキュメントは翻訳しやすく、陳腐化も独立して進む。 メタデータブロックの抜粋は、概要だけを読んで書けるものであるべきだ。ドキュメントを1〜2文で要約できないなら、そのドキュメントは詰め込みすぎである。 ## 新しいレッスンや言語を足し、サイト側に要る登録を伝える 新しい原典ドキュメント: 原典言語ディレクトリの正しいカテゴリー配下にファイルを作成し、初期バージョンを含む完全なメタデータブロックを付ける。そのうえで、新しいドキュメントを表示対象として登録するために公開アプリケーション側の対応変更が必要かどうかを明確に述べる。自動的に表示されると決めつけない。 新しい翻訳: 原典ファイルを、同じカテゴリーパスと同じファイル名で対象言語ディレクトリへコピーし、本文を翻訳し、タイトルや抜粋といった人間が読むメタデータの値を翻訳する。構造上のフィールド名とバージョンの値には手を触れない。バージョンは原典と完全に一致していなければならない。 新しい言語: 新しい言語コードの配下にカテゴリーディレクトリ一式を作成し、構成が他のすべての言語と対称になるようにしたうえで、最初の翻訳ドキュメントを追加し、その言語を公開アプリケーションに登録する。存在するのに登録されていない言語フォルダは、誰にも到達できないコンテンツを生む。 翻訳を書き始める前に、その言語向けのロケール固有スタイルノートが存在するなら必ず読む。ロケールノートは用語の選択、技術用語の音訳、句読法、敬体の水準を扱い、一般のハウススタイルと衝突する場合はロケールノートが優先される。翻訳を依頼された言語にロケールノートが存在しない場合は、黙って独自の慣習を作らず、ノートの新規作成を提案する。 ## 状況レポートを使い、いちばん古い翻訳から最新にする 翻訳のずれ（ドリフト）は、多言語ライブラリにおける既定の失敗モードである。意識的に管理すること。 翻訳作業のセッションは、ディレクトリを手作業でたどるのではなく、ライブラリ全体に対してステータスレポートを実行することから始める。自分が担当する言語と、重要度の高い水準に絞り込む。まったく欠落しているドキュメントと、深刻に陳腐化していると印が付いたドキュメントが最優先、軽度のずれが次点、パッチレベルのずれは最後か、あるいは扱わない。 作業ルールは次のとおり。 - ドキュメントを部分的にしか翻訳していないのに、バージョンを原典と一致させたまま放置しない。最新であると自己申告する中途半端な翻訳は、明らかに欠落している翻訳より悪い。 - 途中で中断せざるを得ない場合は、バージョンを以前の値のままにしておき、レポートがそのファイルを検出し続けるようにする。 - ロケールノートに照らしたレビューを経ずに、機械翻訳のまま公開しない。 - 着手後に原典が変更された場合は、仕上げる前に差分を再確認する。実際に記録することになるバージョンに合わせて仕上げる。 - 最後に、どのドキュメントを最新化したか、どれを意図的に見送ったか、そしてその理由を報告する。次の担当者はそこから優先順位を判断する。