はじめに

NearMeでは創業初期から、日本語・英語を利用するメンバーが混在しており、開発ドキュメントを英語にするか日本語にするかで悩んでいました。 結局そのまま、英語だったり日本語だったりのドキュメントが混在する状態になり、 結果的に、十分にドキュメントが整備できているとは言えない状況でした。

そんな中、昨今のAIの進化により、翻訳の精度が向上し、開発ドキュメントの多言語化が容易になってきたことから、 今回、開発ドキュメントの基盤を見直し、多言語対応を進めたので、その取り組みについて紹介します。

これまでの運用

これまでも開発に関する情報は、散在しつつも一定数存在していました。 Git上ではREADMEやコードコメントを可能な限り記載し、それらはすべて英語で書くようにしていました。 また、設計や運用に関する情報はNotionで雑多に書かれていました。 ただし、Notion上のドキュメントは日本語主体で、一部のみ英語化されている状態で、また、ドキュメントを書く人も設計者や特定のメンバーに限られる傾向がありました。

体系的な一次情報としての開発ドキュメント基盤の整備が常に求められてきましたが、多言語対応が大きな課題でした。

ドキュメントサイトの再構築

今回、開発ドキュメントをAstroベースのサイトとして再構築しました。ドキュメントはMarkdownで管理し、Git上でバージョン管理を行います。 Astroを選定した理由としては、シンプルな構成であること、Markdownとの親和性が高いこと、多言語対応しやすいことなどがあります。

Notionにも翻訳機能があり、活用することもありますが、 MarkdownでVSCodeなどのエディタで編集するときに、翻訳のみならず、AIを活用した文章の改善も行いやすくなることから、Markdownでの管理を選択しました。

多言語化についてはさらに、エディタ上のAIだけでなく、GitHub Actionsを利用して自動化しています。 プルリクエストが作成・更新されると、GitHub Actionsがトリガーされ、AIを活用して翻訳を行い、翻訳結果をコミットするようにしています。 AIへの指示は大まかには以下のようにしています。

• ベースブランチとの差分から、変更された日英ドキュメントだけを抽出する
• 変更された各ファイルについて、対向言語側の対応ファイルを作成または更新する
• 変更ファイルと対応ファイル以外は読まない・変更しない
• 既存本文は基本的に維持し、必要であればメタデータの version だけ更新する
• title と description は翻訳し、日本語は自然なですます調に、英語は簡潔で直接的にする
• version はベースブランチと比較し、作者が上げていなければ変更側を +1 し、対向言語側も同じ値にそろえる
• 内部リンクの言語パス（日英）を相互に置換する
• 画像名の言語サフィックス（例: -jaと-en）も対応して置換する
• コードブロックは翻訳せず、そのまま保持する

つまり、変更が入ったドキュメントだけを対象に、翻訳内容とバージョン整合性を崩さずに日英を自動で揃えています。

別途、周辺ツールとして、メタデータの version の差分を検出して一覧表示するスクリプトも用意しています。

運用してみて

翻訳品質に関しては、AIの進化により、修正点はほぼなく実用的なレベルになっています。

以前は英語で直接書いていたドキュメントに関しても、母国語で十分に吟味して書けるようになったことで、ドキュメントの質も向上したと感じています。 また、ドキュメントを書くハードルが下がったことで、より多くの内容をドキュメントとして残せるようになったと感じています。

まだ整備すべきドキュメントは多くありますが、少なくとも情報を残しやすい状態にはなったと感じています。

技術ブログも同じ基盤へ

今回構築した仕組みは、開発ドキュメントだけでなく、この技術ブログにも適用しています。 もともと技術ブログは別サービスで運用していましたが、多言語対応や運用方法の統一を考え、同じAstroベースの基盤へ移行しました。 開発ドキュメント向けに構築した仕組みをそのまま活用できたことに加え、AIを活用しながら実装を進めたことで、短期間で移行を完了することができました。 結果として、開発ドキュメントと技術ブログの両方を同じ仕組みで運用できるようになりました。

おわりに

AIの進歩によって、翻訳コストだけでなく、サイト構築や運用基盤の整備コストも大きく下がってきています。 今回の取り組みでは、多言語化のみならず、改めて、継続的にドキュメントを書ける基盤を整備できたことが大きな成果でした。 AIを活用した開発が一般的になる中で、開発ドキュメントの重要性は今後さらに高まっていくと考えています。 今回整備した基盤を活用しながら、今後もドキュメントの拡充を進めていきたいと思います。