GitLab製品ドキュメントが日本語で利用可能に - 構築と自動化までの流れ

本日、GitLab製品ドキュメントの日本語版を docs.gitlab.com/ja-jp にて公開しました。GitLabの包括的なドキュメントを世界中のユーザーに利用していただけるようにする取り組みの、重要な第一歩です。

日本市場特有の課題

日本は世界最大規模の経済圏の一つであり、エンタープライズソフトウェアにとって極めて重要な市場です。しかしながら、日本市場には独特の課題も存在します。高度な技術力と大規模な開発者コミュニティを有する一方で、英語の習熟度が多くのユーザーにとって大きな障壁となっているのが現状です。

日本の開発者やDevSecOpsチームの皆様は、英語のみのドキュメントに課題を感じています。これは、EF英語能力指数における日本の順位にも表れています。この言語の壁は、学習のスピードに大きく影響し、最終的には日本の組織内でプラットフォームの評価・導入・推進を行う際の意思決定にも影響を及ぼします。

日本のお客様やパートナー企業の皆様から直接聞いた声として、英語のみのドキュメントは単なる不便さではなく、GitLabを最大限に活用する上での障壁となっていたとのことでした。この影響は、ユーザージャーニーのあらゆる段階に及んでいました。初期評価の段階ではGitLabの機能を十分に理解することが困難であり、日常業務では問題解決に必要以上の時間を要し、新機能やベストプラクティスの習得も遅れがちになっていました。

日本のような競争が激しく成熟した市場においては、この言語の壁がGitLabの市場での存在感に直接的な影響を与えていました。日本企業がエンタープライズソフトウェアを評価する際、包括的な日本語ドキュメントの提供は、その市場への長期的なコミットメントを示すものです。それは、提供企業が形だけの取り組みではなく、日本のユーザーの皆様のジャーニー全体を真摯にサポートしていくという姿勢を示すものです。

このような課題に対応し、日本市場への私たちのコミットメントを示すため、GitLabにおけるドキュメントの作成・メンテナンス方法と統合された、ローカライゼーション基盤を一から構築しました。

Docs-as-Code原則に基づくローカライゼーション

GitLabのドキュメントは、他のコードと同じように扱い、GitLabプロジェクト内で製品コードと一緒に管理し、マージリクエストを通じて運用しています。ドキュメントはバージョン管理下に置き、共同でレビューし、CI/CDパイプラインで自動テストを実施します。テストでは言語、フォーマット、リンクの問題をチェックします。英語版と日本語版のドキュメントサイトは、Hugoという静的サイトジェネレーターで動的に生成し、変更のマージ後にデプロイするため、ユーザーは常に最新の情報にアクセスできます。

ドキュメントは広範かつ包括的で、GitLab、GitLab Runner、Omnibus GitLab、GitLab Charts、GitLab Operator、GitLab CLI（glab）など、さまざまなソースプロジェクトからコンテンツを集約しています（詳細はアーキテクチャを参照）。この膨大な規模と速い更新頻度が、ローカライゼーションにおいて大きな課題となりました。ソース英語プロジェクトの継続的な進化に遅延なく対応するため、こうした独特の複雑さに対応でき、完全にローカライズされたサイトをエンタープライズに求められるレベルで提供し、なおかつCI/CDパイプラインの要件を満たすローカライゼーション基盤を設計する必要がありました。

GitLabドキュメントのローカライゼーション方法

最初の日本語ローカライゼーションでは、既存の英語コンテンツ構造内に新しいフォルダーを統合する戦略を採用しました。具体的には、ソースのmarkdownファイルを保存する各プロジェクト内に、 doc-locale/ja-jp フォルダーを導入しました。このアーキテクチャにより、翻訳をソースコンテンツのすぐ隣に配置しながら、明確な組織的分離を維持できます。それだけでなく、英語ドキュメントで使用しているのと同じ堅牢なバージョン管理、確立されたレビューとコラボレーションのワークフロー、さらには一部の自動品質チェックを、翻訳コンテンツにも適用できるようになります。

この日本語ドキュメント用に構築された国際化基盤は、将来の言語拡張に向けたスケーラブルな基盤を提供します。アーキテクチャ、ツール、プロセスが整ったことで、GitLabを世界中のユーザーが利用できるようにするという私たちのコミットメントを継続し、今後さらに多くの言語をサポートする準備が整いました。

スピードと品質のバランスを取ったAI支援翻訳ワークフロー

コンテンツを翻訳する際、戦略的な段階的アプローチを採用し、英語のページビュー数に基づいてページの優先順位を付けました。アクセス数の多いページから順にAI翻訳を実施し、その後、人間の翻訳者による包括的なレビューを行い、これらの優先ページが人間によるレビューサイクルを完了するまで、意図的に後続のフェーズを一時停止しました。この意図的な順序付けにより、最も重要なコンテンツから、堅牢でキュレーションされた翻訳メモリとタームベースを構築できました。これらの言語資産により、残りのすべてのコンテンツの翻訳速度が向上し、品質も改善されました。並行して、この初期フェーズはGitLab側の技術インフラのテストの場としても機能しました。これを活用してCI/CDパイプラインを反復的に強化するとともに、翻訳とポストエディットのAIスクリプトを改良し、翻訳マージリクエストのレビュープロセスを確立しました。

世界中のユーザーに最新のドキュメントを提供しながら、高品質な翻訳コンテンツを保証するため、人間の翻訳者によるポストエディットを伴うAI支援翻訳ワークフローを実装しました。その構成は以下の通りです。

• フェーズ1: AI翻訳。スタイルガイド、GitLab UIコンテンツの翻訳、用語データベース、元ファイルのコンテキストなど、GitLab固有のコンテキストを組み込んだカスタムAI翻訳システムを構築しました。このシステムは、GitLabの特殊なmarkdown構文（GLFM）を適切に処理し、プレースホルダー変数、アラートボックス、Hugoショートコード、GitLab固有の参照など、標準的な翻訳ツールでは標準で処理できない要素を保護します。
• フェーズ2: 人間の翻訳者によるレビュー。技術コンテンツを専門とする日本語の翻訳者が、AI翻訳をレビューして洗練させます。翻訳者は、GitLabの日本語スタイルガイド、翻訳メモリ、用語データベースを使用して、正確性、自然な言語の流れ、文化的な適切性を確保します。これらのレビュー済み翻訳は、サイト上でAIバージョンを段階的に置き換えていきます。

技術的な課題と解決策

GitLabの膨大なドキュメントをローカライズしながら、Docs-as-Code原則とCI/CD駆動のパブリッシングワークフローを維持するには、大きな技術革新が必要でした。課題は翻訳そのものにとどまりません。複雑なmarkdown構文の保持、自動テスト基準の維持、シームレスなコンテンツフォールバックの確保、そして複数のソースプロジェクト全体での継続的な更新プロセスの構築が求められました。

英語のmarkdownファイルの構文が複雑だったため、翻訳管理システム（TMS）内でカスタムコードと正規表現を開発し、コードブロック、URL、その他の翻訳対象にすべきでない機能要素を保護しました。

英語コンテンツの生成方法の特性上、英語フォールバックの仕組みを確立しました。基本的に、日本語翻訳がまだ準備できていない場合、ローカライズされたサイトは、翻訳されたナビゲーションとUIとともに英語コンテンツをシームレスに表示することによって404エラーを防ぎ、Hugoのレンダリングシステムを介して言語コンテキストを維持します。

また、ローカライズされたナビゲーションとリンクを強化し、動的に調整してロケールを維持するようにしました。翻訳に送信する前に英語ファイルを前処理することで、翻訳ファイルにアンカーIDを追加しました。これにより、リンクからドキュメントページに移動するユーザーの体験が向上します。一貫したアンカーIDにより、どちらの言語に切り替えても、ページ内の正しい場所に到達できます。

CI/CDパイプラインも拡張し、英語ドキュメントと同じ品質基準に従って、翻訳マージリクエスト内のローカライズされたコンテンツをテストできるようにしました。これにより、無効なHugoショートコード、リンク内のスペース、裸のURLを検出できます。また、孤立したファイルや、ターゲットファイルのないリダイレクトファイルも特定します。翻訳ドキュメントを含むマージリクエストで実行されるジョブは、GitLabプロジェクトの.gitlab/ci/docs.gitlab-ci.ymlファイルで確認できます。

一元化された翻訳リクエストシステムがワークフロー全体を統制しています。このシステムは、英語ファイルの監視、新規および更新コンテンツの識別、翻訳用ファイルのルーティング、翻訳マージリクエストの自動作成を行います。さらに、翻訳リクエスト内のファイルステータスの追跡と監査証跡の維持も担当します。ドキュメントの翻訳では、430件の翻訳マージリクエスト（各1〜10個のファイルを含む）を処理しました。

その結果、英語コンテンツの更新と同期し、重要な情報にユーザーが素早くアクセスできる日本語ドキュメント体験が実現しました。ユーザーは自分の言語でコンテンツを発見し、翻訳中のコンテンツのみ英語が表示されます。最新機能に素早くアクセスできると同時に、GitLabの品質基準も保たれています。これらすべてが、将来の言語展開とドキュメントの成長のための、持続可能でスケーラブルな基盤を構築しています。

技術的な詳細については、GitLab製品ドキュメントハンドブックページをご覧ください。

docs.gitlab.comの日本語版へようこそ

GitLabを長年使用されている方も、これから始める方も、このローカライズされたドキュメントによって、DevSecOpsの取り組みがよりスムーズで利用しやすくなることを心から願っています。

私たちのローカライゼーションの取り組みは始まったばかりで、改善のために皆様のフィードバックが非常に重要です。翻訳の問題に気づいた場合、改善の提案がある場合、または日本語ドキュメントの使用体験をフィードバックしたいだけでも、遠慮なくお知らせください。フィードバックイシューからコメントをお寄せいただけます。

ローカライゼーション基盤を進化させていく中で、当面の優先事項は、日本語の検索機能の向上と、英語の更新と日本語翻訳との間のタイムラグを最小限に抑えるための継続的なローカライゼーションワークフローの加速です。より良いサービスを提供できるよう取り組む中で、日本のコミュニティの皆様の継続的なサポートと忍耐に感謝いたします。GitLabを日本のチームにとって最高のDevSecOpsプラットフォームにすることに私たちは全力で取り組んでおり、包括的な日本語ドキュメントはその道のりにおける重要な一歩です。

ぜひ docs.gitlab.com/ja-jpをお試しください。