日本語APIドキュメントのローカライズ：
デベロッパーアドボケイトが見落とすこと

まとめ

日本のエンジニアはドキュメントの品質をAPIの品質の代替指標として扱います。日本語ドキュメント内に英語のコードコメントがある、エラーメッセージが機械翻訳で実行可能なガイダンスがない、またはSDKのreadmeがレビューなしで翻訳ツールにかけられたように読めるといった状況に遭遇した開発者は、サポートチケットを提出しません——別のAPIを選びます。こうした摩擦を一貫して生み出す5つの領域は、コードサンプルのコメント、エラーメッセージのコピー、エンドポイントの命名とパラメータの説明、認証フローの説明、そしてSDKのreadmeの文体です。それぞれは集中したローカライズ作業で修正できますが、それぞれが日本の開発者にとって具体的にどう重要かをチームが理解している場合に限ります。

重要なポイント

• 日本語ドキュメントのコードサンプルコメントは日本語にすべきです——英語のインラインコメントが混ざっていると、ローカライズが本文で止まり、肝心のコード例まで届いていないことが開発者に分かってしまいます。
• エラーメッセージには翻訳された英語のガイダンスではなく、日本語固有のガイダンスが必要です——急いでデバッグしている日本の開発者に必要なのは、顧客向けUIの丁寧な言い回しではなく、問題にまっすぐ触れるエラー文です。
• エンドポイントの命名とパラメータの説明は一貫した日本語用語を使う必要があります——UI用語集とAPIリファレンスで用語が食い違うと、エンドユーザーが見る画面に合わせて連携を作っている開発者が迷います。
• 認証フローのドキュメントは日本のエンタープライズのセキュリティ要件に明示的に対応しなければなりません——IPアローリスト、データ所在地、監査ログの要件は、日本の大企業のセキュリティチームにとって例外的な話ではなく、標準の評価項目です。
• SDKのreadmeのトーンはカジュアルな開発者文化と正式なエンタープライズ敬語の間にある文体を必要としています——英語の開発者コミュニティでうまくいく口調は日本語にそのまま移せず、機械翻訳するとくだけすぎるか、硬すぎる文になります。

APIドキュメントは信頼の判断材料：日本の開発者はこう評価する

多くの市場では、開発者はドキュメント、価格、実際に連携してみた感触を合わせてAPIを評価し、どれから見るかは人や状況によって違います。日本ではこの順番がほぼ決まっています。まずドキュメントの質を見て、最初のAPIコールを打つ前に、信頼できる相手かどうかをそこで判断します。

この傾向には、文化的な理由と実務上の理由の両方があります。日本の大企業の開発では、外部APIを連携先として承認するまでに、開発者、チームリーダー、プロジェクトマネージャー、さらにセキュリティやコンプライアンスの審査担当など、多くの関係者がかかわるのが普通です。それぞれが自分の技術レベルでドキュメントを読みます。開発者はリファレンスを、チームリーダーは概要とクイックスタートガイドを、セキュリティ担当は認証とデータ処理の章を読みます。どの層で不完全さが見えても、評価全体が止まってしまいます。

一部だけローカライズされたドキュメント——本文は日本語、コードコメントは英語、エラーメッセージは未翻訳、changelogは英語のみ——は、「ほぼ日本語」ではなく「未完成」と受け取られます。日本の大企業の関係者は、不完全さをリスクの兆候と見ます。ドキュメントを仕上げなかったチームなら、セキュリティ審査やSLAの約束、サポート体制も仕上がっていないのではないか、と考えるのです。

コードサンプルのコメント：APIローカライズで最も飛ばされがちな工程

APIドキュメントのローカライズ範囲で、コードサンプルのコメントはほぼいつも最後に回され、多くのプロジェクトでは丸ごと削られます。理由は分かります。コードはコードで、変数名は英語、ロジックも言語に関係なく同じです。コメントは飾りのようなもので、英語のままでも開発者体験は損なわれないと考えられがちです。

日本の開発者の受け止め方は違います。コードサンプルは、APIドキュメントの中で一番コピーされ、書き換えて使われる部分です。サンプルをコピーし、自分のコードに合わせて直しながら英語のコメントを頭の中で訳す日本の開発者は、2つの作業を同時にこなしています。さらに問題なのは、そのコードを社内で共有するときです。プルリクエストでも、チームのwikiでも、後任の開発者向けのオンボーディング資料でも、英語のコメントがそのまま付いていきます。その結果、社内に蓄積されるそのAPIの知識がまるごと二言語混じりになり、後から触る開発者全員に余計な手間をかけ続けます。

「開発者は英語でも大丈夫」という考えは、状況を見誤っています。日本の開発者の多くは英語の技術文書を読み慣れています。問題は読めるかどうかではありません。一貫性とプロらしさ、そしてこの不統一が、日本市場をどこまで本気で考えているかについて何を伝えてしまうかです。英語のドキュメントに日本語のインラインコメントが混ざっていれば、英語圏の開発者も同じちぐはぐさに気づくはずです。

エラーメッセージのローカライズ：開発者向けツールには顧客向けUIとは違う文面が要る

APIのエラーメッセージは、ローカライズの対象の中でも特殊な位置にあります。読むのは開発者ですが、表示されるのはエンドユーザーの目にも触れる本番環境です。技術的に正確でなければならない一方で、短すぎて開発者が次の手を打てないようでも困ります。そして何より、連携の失敗をデバッグしている開発者に合う口調は、一般向けアプリでエラーに出会ったお客様に合う口調とは違います。

多くのローカライズチームは、UIのエラーメッセージと同じトーンの指針を、APIのエラーメッセージにも当てはめます。その結果、一般向けとしては丁寧でちょうどよくても、開発者にとっては回りくどく、次に何をすればよいか分かりにくいエラー文ができあがります。深夜2時にレート制限に引っかかった日本の開発者が知りたいのは、何が起きたのか、どうすればよいのかです。丁寧に練られたお詫びではありません。

書き方の違いは、開発者が構築したアプリケーションを通じてエンドユーザーに表出するエラーメッセージにとっても重要です。日本のSaaSプロダクトがあなたのAPI上に構築されてエラーメッセージをユーザーに公開する場合、開発者向けに書いたエラーは、一般ユーザーの画面ではぎこちなく読まれます。解決策は2層のエラーメッセージシステムです：完全な技術的詳細を持つ開発者向けメッセージと、開発者がコンシューマーコンテキストでオプションとして表示できるユーザー向けメッセージ文字列。どちらも日本語ローカライズが必要です；同じ文字列であってはなりません。

エンドポイントの命名とパラメータの説明：プロダクトUIとの用語の一貫性

連携を作っている日本の開発者からよく出る不満のひとつが、APIリファレンスの日本語用語が、連携先の製品UIと違うことです。UIでは「顧客名」と呼ばれている項目が、APIではcustomerName、リファレンスの説明では「顧客の名前」になっている。技術的には間違っていませんが、UI用語集とは合っておらず、開発者がAPIの項目をユーザー向けのUI要素に対応づけるときに混乱を招きます。

この問題は、UIの日本語用語集はあるのに（本来あるべきものです）、APIリファレンスの日本語用語集がない場合にさらに悪化します。開発者は、別々に日本語化された2つの語彙を、橋渡しなしで頭の中ですり合わせることになります。決済処理、アイデンティティ管理、分析のような複雑な連携では扱う用語の数が多く、食い違いが積み重なって大きな負担になります。

解決策は、製品UIとAPIリファレンスの両方を対象にした共通の日本語用語集を作り、唯一の正本として管理して、どちらを日本語化するときにも使うことです。ほとんどの製品では大がかりな文書にはなりません。よく使う製品固有の用語50〜100語と、合意した日本語訳を並べたリストです。このリストをきちんと保守しておけば、APIリファレンスに限らず、あらゆるローカライズの場面で効いてきます。

認証フローの説明：日本の大企業のセキュリティ審査担当に向けて書く

日本の大企業向けAPIの認証ドキュメントは、ひとつの文書ではなく、読者の違う2人に向けた2つの文書です。開発者はクイックスタートのOAuthフローを読み、10分で動くトークンを手に入れたいと考えています。セキュリティ審査担当は、プロジェクトを進めてよいと承認する前に、APIが社内のセキュリティ基準を満たしているかを認証ドキュメントで確かめます。この2人の読者には、違う情報を、違う硬さの文体で届ける必要があります。

開発者向けの認証ドキュメントは、残りのAPIリファレンスと同じ中立的で技術的な文体であるべきです。セキュリティ向けのドキュメント——トークンのスコープ、データ所在地、監査ログ、IPアローリスト、コンプライアンス認証をカバーするセクション——はより改まった文体で書かれる必要があります。日本のエンタープライズセキュリティチームは正式な情報セキュリティポリシーで動いており、セキュリティコンテキストでカジュアルまたは会話的な言語を使うドキュメントは、ベンダーがセキュリティガバナンスを真剣に捉えているかどうかについての疑念を生じます。

SDKのreadmeのトーン：開発者文化とエンタープライズ敬語の間の文体を見つける

英語のSDKのreadmeは特定の文化的な空間を占めています：インフォーマルで、直接的で、しばしば意見が強く、仲間内であることを示す口調で書かれています。「Get started in 5 minutes」「it just works」「contributions welcome」——これらのフレーズは、オープンソースコミュニティで時間を過ごした開発者であれば誰でも認識できます。これらはそのまま日本語に翻訳できません——文体を大きく変える必要があります。

SDKのreadmeで一番多い機械翻訳の失敗は、英語の開発者文化のくだけた言葉が、翻訳ツールの初期設定しだいで、ぎこちない口語か硬すぎる文語のどちらかに変わってしまうことです。どちらになっても、開発者コミュニティの感覚とソフトウェア文書の日本語の作法の両方を分かっている人が書いた文には見えません。

日本語SDKのreadmeで目指す文体は、日本の開発者が実際に社内技術ドキュメントを書くときに使用するもの：丁寧語（丁寧な形）、です/ます語尾、明確な命令形の構文、スラングと重い敬語の両方の回避です。チームの他の開発者向けにドキュメントを書く丁寧な同僚の文体であり、エンタープライズカスタマーに書くベンダーの文体ではありません。

変更履歴とリリースノート：チームが決まって後回しにする最後の部分

Changelogは、APIドキュメントのローカライズを始めた段階では、まず対象範囲に入りません。エンジニアが書くもので、更新頻度が高く、短く、読むのは主にすでに連携を済ませていて英語でも対応できる開発者だから、というのが理由です。どれも半分は当たっています。しかし、どれも日本の開発者に英語だけのchangelogを出してよい理由にはなりません。

あなたのAPIで本番の連携を作っている日本の開発者は、changelogをこまめに確認しています。破壊的変更、廃止予定、新しいエンドポイント、レート制限の変更は、どれも開発者側で対応が必要です。本番の3週間前に破壊的変更を告知しても、英語のchangelogなら、その効果は開発者が英語で読み、理解し、対応できるかどうかにかかっています。しかも時間に追われながら、日本語で動くプロジェクトチームに影響を説明しなければなりません。

Changelogのローカライズは、運用面では簡単です。Changelogは短く、構造が決まっていて、書き方のパターンも一定しています。バージョン番号、日付、Added / Changed / Fixed / Deprecated / Removedに分けた変更点のリストです。この構造なので、別プロジェクトにするのではなく、リリース手順の標準的な工程のひとつとして軽く日本語化するのに向いています。Changelogの項目を日本語化する追加コストはわずかです。英語で告知された破壊的変更を日本の開発者が見落として本番障害が起きたときのコストは、そうはいきません。

「サーバー」か「サーバ」か：本国ドキュメントを日本向けに出す前に決めておく長音の表記ルール

本国の英語ドキュメントを日本向けに出す担当者が、翻訳の前に決めておくべきことがひとつあります。server、user、parameter、browser のように英語の語末が -er で終わる語を、長音符「ー」を付けて書くか省くかです。訳者が複数いる、機械翻訳と人手の修正が混ざる、UIとAPIリファレンスを別のチームが訳す——こうした条件がそろうと、同じページの中に「サーバー」と「サーバ」が並ぶ状態はほぼ確実に起こります。

よりどころとしてよく参照されるのが、1991年（平成3年）の内閣告示「外来語の表記」です。文化庁が公開している本文を確認すると、留意事項その2の「III 撥音，促音，長音その他に関するもの」に、長音は原則として長音符号「ー」を用いて書くとあり、その注3で、英語の語末の -er、-or、-ar などに当たるものは原則としてア列の長音とし「ー」を用いる、ただし慣用に応じて「ー」を省くことができる、と定めています。例として挙がっているのはエレベーター、ギター、コンピューター、マフラーで、付録の用例集には「エレベーター／エレベータ」「コンピューター／コンピュータ」のように両方の形が併記されています。

見落とされやすいのは前書きです。この告示は法令・公用文書・新聞・放送など一般の社会生活での表記のよりどころであり、科学・技術などの各種専門分野の表記にまで及ぼそうとするものではない、と明記されています。つまり告示は「付けるのが原則、省く慣用も認める」という幅を示しているだけで、技術文書でどちらを採るかは、各社が自分で決めて文書化するしかありません。決めずに訳し始めることが、表記揺れの一番の原因です。

表記統一表を作る手順（半日で終わる規模）

1. 方針を1行で決める。「英語の語末 -er / -or / -ar に当たる長音は付ける」または「省く」。本国のUI文字列がすでに日本語化されている場合は、既存UIの表記に合わせるのが最も手戻りが少ない選択です。
2. 既存の日本語資産から対象語を洗い出す。UI文字列、ヘルプセンター、過去の日本語ドキュメントを「サーバ」「ユーザ」「パラメータ」「ブラウザ」「フォルダ」「コンピュータ」などで検索し、長音符あり・なしの出現数を数えます。どちらが多数派かが、手順1の判断材料になります。
3. 10語程度の統一表にまとめる。サーバー、ユーザー、パラメーター、ブラウザー、フォルダー、コンピューター、プロバイダー、コンテナー、ヘッダー、マネージャーのように、APIドキュメントで頻出する -er / -or 語を先に押さえます。「エラー」「キー」のように長音符を省くと語として成り立たない語は、方針にかかわらず付けたままにする、と注記しておきます。
4. 例外を明記する。固有名詞（製品名・会社名）や、コード中の識別子・UIに表示されない英字表記は対象外です。告示の前書きも、会社名や商品名など固有名詞でこれによりがたいものには及ぼさないとしています。
5. 統一表を用語集と同じ場所に置き、訳者と機械翻訳の後処理の両方に渡す。前節の用語集（UIとAPIリファレンスで共有するもの）の先頭に置けば、管理する表が増えません。

告示の本文と付録の用例集は、文化庁のウェブサイト（国語施策情報「外来語の表記」）で確認できます。社内の表記方針を決める際は、担当者の記憶ではなく原文を一度読んでおくことをおすすめします。

よくある質問