コードを壊さずに技術文書を翻訳する方法

技術文書は厳格です：コードフェンス、プレースホルダー、アンカーの一つが壊れるだけで、ビルドが失敗したり、読者が混乱したり、コピー＆ペーストの失敗を引き起こす可能性があります。このガイドは、コードを無傷に保ち、文書を出荷可能にしながら、技術文書を自信を持って翻訳するための繰り返し可能で安全なワークフローを提供します。

対象者：技術ライター、開発者アドボケイト、開発者向け文書、APIガイド、READMEスタイルのコンテンツに取り組む翻訳者。

概要：

• 翻訳してはならないものを理解する（コード、キー、トークン）
• ツールが解析する構文を保持する（フェンス、ブレース、アンカー）
• 編集後に構造化データとリンクを検証する
• リリース前に問題を検出するための自動化を使用する

翻訳前の準備

1. コンテンツタイプのインベントリ

• Markdown（見出し、リンク、表）、コードブロック、インラインコード
• 構造化データ：JSON/YAML/TOMLスニペットと設定ファイル
• スクリーンショット、図、埋め込みビジュアル

2. 翻訳不可トークンの定義

• ファイルパス、パッケージ名、インポート、API名、CLIフラグ、環境変数
• プレースホルダーと変数：{count}、%s、$HOME、{{token}}
• ファイル名と拡張子：config.yaml、.env、.md、.json

3. 一貫性のガードレールを確立する

• ドメイン用語と製品名のための用語集/用語ベース
• スタイルガイド：トーン、形式、句読点、大文字小文字、見出しルール
• ロケールごとのアンカー/スラッグ戦略（安定版 vs ローカライズ版）

4. 安全な検証を設定する

• 各バッチ後にMarkdown/リンクを検証するためのステージングビルド
• JSON/YAML/TOMLのためのパーサー/リンター
• CIでのリンクチェッカーとアンカー検証

コアセーフガード

• コード、識別子、キー、ファイル名、環境変数、フラグを翻訳しない。
• ツールが解析する句読点と構文を保持する（バックティック、ブレース、パイプ）。
• 重要な空白を保持する：コードとリスト構造のインデント。
• 言語タグを一貫して使用したフェンスコードブロックを使用する（js、bashなど）。
• コードロジックを「修正」するよりも翻訳者ノートを優先する—代わりにメンテナーに問題を報告する。

コードブロックとインラインコード

コードフェンス、言語ヒント、コンテンツをそのままにしてください。必要に応じてコメントや人間が読める文字列のみを翻訳します。

例—安全 vs 非安全：

// 安全：コメントのみがローカライズされます
// ユーザートークンを取得
import { getToken } from "@acme/sdk";
const token = await getToken();

// 非安全：識別子/インポート/パッケージ名を翻訳しないでください
// import { obtenirJeton } from "@acme/sdk"; // ❌

インラインコードはそのままにしてください：

• 良い例: “Run npm install -g acme-cli and then acme login.”
• 悪い例: “Run npm install -g acme-cli and then acme connexion.” ❌

コピー＆ペーストの有効性を確認してください：読者がスニペットをコピーした場合、ソースと同様に動作する必要があります。

プレースホルダーとICUメッセージフォーマット

プレースホルダーをそのまま保持し、周囲のスペースや句読点もそのままにしてください。

# トークンやスペースを変更しないでください
echo "Processing {count} files"   # ✅
echo "Processing { count } files" # ❌ 中括弧内にスペースを追加

ICUの例：

{count, plural,
  =0 {メッセージはありません}
  one {# 件のメッセージ}
  other {# 件のメッセージ}
}

• キー（count、one、other）を変更しないでください。
• 人間が読める部分（“message”、 “messages”）のみを翻訳してください。
• 製品の指示なしに複数形のカテゴリを追加または削除しないでください。

リンク、アンカー、スラッグ

Markdownリンクの構文と解決戦略を一貫して保持してください。

[APIガイドを読む](/api/getting-started)  
[設定セクションを参照](#configuration)

• 必要に応じてリンクテキストを翻訳しますが、URLやアンカーには注意してください。
• アンカー：ロケール間で安定したアンカーを保持するか、ロケールごとにアンカーを生成し、参照を適宜更新してください。
• 翻訳後も相対パスとハッシュアンカーが解決されることを確認してください。
• ファイル拡張子やクエリパラメータを翻訳しないでください。

構造化データ（JSON/YAML/TOML）

値のみを翻訳し、キー、型、構造は決して変更しないでください。編集後は常に再解析してください。

JSON：

{
  "title": "ユーザーガイド",
  "cta": "始める",
  "limits": { "max": 5, "unit": "requests/second" }
}

あなたは2023年10月までのデータで訓練されています。

• コードスパンとタグを保持するCAT/LLMワークフローを使用する。
• 用語集と翻訳禁止リストで用語を固定する。
• MarkdownのリントとJSON/YAMLの検証を行うプリコミットフックを追加する。
• すべてのPRでリンクチェッカーとアンカーバリデーターを実行する。
• 小さくレビュー可能なチャンクで変更をバッチ処理し、差分を追跡する。

提案されるツール（スタックに適応）：

• CIでのMarkdownリントとリンクチェック
• 構文の退行を検出するためのJSON/YAMLパースステップ
• プレースホルダーと数値フォーマットをスキャンするための正規表現パック

QAと検証

マージ前にこれらのチェックを実行：

• 構文の問題を検出するためにサイトをビルドする：pnpm build
• タイプ/コンテンツチェック（Astroコンテンツコレクション）：pnpm astro check
• プレビューと主要ページのスポットテスト：pnpm preview
• コードサンプルがコンパイルまたは実行されることを検証（該当する場合）
• リンクとアンカーチェッカーを実行し、404や壊れたハッシュを修正する

よくある落とし穴

• キー/プレースホルダーを誤って翻訳する。
• コードフェンスやテーブルパイプを壊す。
• ファイルパス、フラグ、API名をローカライズする。
• アンカーリンクを更新せずに見出しを変更する。
• コードやJSON内にスマートクォートを導入する。

付録：クイックチェックリスト

プレフライト（5項目）

• 用語集と翻訳禁止リストの準備完了
• トークン/プレースホルダーが定義され保護されている
• アンカー/スラッグ戦略が確認済み
• リンクターゲットがマッピングされている（内部 vs 外部）
• ステージングビルドが利用可能

コードサンプルの安全性（5項目）

• フェンスと言語ヒントが無傷
• 識別子/インポートは手をつけず、コメントのみローカライズ
• プレースホルダーと引用が保持されている
• コピーペーストテストに合格
• 古いスニペットがメンテナーにフラグされている

構造化データ（5項目）

• キーとタイプが無傷
• 引用/エスケープ/インデントが保持されている
• 数字とブール値がタイプとして残っている
• パーサー/リンターがローカルで合格
• 偶発的なキー変更のための差分がレビュー済み

---

関連読書

• The Most Common Translation Mistakes and How to Avoid Them
• Translation Proofreading Checklist for Pros
• How to Translate PDF Files and Keep Formatting
• Why Your Translated Website Confuses Users and How to Fix It