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

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

対象者：技術ライター、開発者アドボケイト、開発者向け文書、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など）。
• Prefer translator notes over “fixing” code logic—flag issues to maintainers instead.

Code Blocks and Inline Code

Keep code fences, language hints, and content intact. Translate only comments and human‑readable strings if required.

Example—safe vs unsafe:

// SAFE: Only the comment is localized
// Obtains a user token
import { getToken } from "@acme/sdk";
const token = await getToken();

// UNSAFE: Do not translate identifiers/imports/package names
// import { obtenirJeton } from "@acme/sdk"; // ❌

Inline code must stay verbatim:

• Good: “Run npm install -g acme-cli and then acme login.”
• Bad: “Run npm install -g acme-cli and then acme connexion.” ❌

Validate copy‑pasteability: If a reader copies any snippet, it should run as in the source.

Placeholders and ICU MessageFormat

Preserve placeholders exactly, including spacing and punctuation around them.

# Do not alter tokens or spacing
echo "Processing {count} files"   # ✅
echo "Processing { count } files" # ❌ adds spaces inside braces

ICU example:

{count, plural,
  =0 {No messages}
  one {# message}
  other {# messages}
}

• Do not change keys (count, one, other).
• Translate only the human‑readable parts (“message”, “messages”).
• Do not introduce or remove plural categories without product guidance.

Links, Anchors, and Slugs

Keep Markdown link syntax and resolve strategy consistent.

[Read the API guide](/api/getting-started)  
[See the config section](#configuration)

• Translate link text if needed; be cautious with URLs and anchors.
• Anchors: either keep stable anchors across locales or generate per‑locale anchors and update references accordingly.
• Verify relative paths and hash anchors still resolve after translation.
• Do not translate file extensions or query params.

Structured Data (JSON/YAML/TOML)

Translate values only—never keys, types, or structure. Always re‑parse after editing.

JSON:

{
  "title": "User Guide",
  "cta": "Get Started",
  "limits": { "max": 5, "unit": "requests/second" }
}

• Keys like title, cta, limits, max must remain unchanged.
• Numbers, booleans, and nulls stay as types, not words.

YAML (watch folded scalars):

note: >
  Lines are folded into a single paragraph.
  Keep indentation and markers intact.

• Preserve quoting, escapes, indentation, and trailing commas (where applicable).

Filenames, CLI, and API Names

• Do not translate filenames, package names, endpoints, or CLI flags.
• Keep case sensitivity exactly as in source (e.g., --DryRun vs --dry-run).
• Maintain commands verbatim; add callouts if locale‑specific differences exist.

# Correct
kubectl get pods --namespace default

# Wrong (flag translated) ❌
kubectl get pods --nom-espace defaut

Markdown Gotchas

• Tables: keep pipes and alignment; do not break columns.

| Option | Description           |
|-------:|-----------------------|
|   -v   | Verbose output        |
|   -q   | Quiet mode            |

• 警告/注記：使用しているツールのマーカーを保持します。
• インラインHTML：タグや属性に触れないでください。
• 脚注：IDと順序を保ちます。
• スマートクォート：コード内ではストレートクォートを優先します。

ビジュアルとアクセシビリティ

• altテキストはピクセル内容ではなく意味に合わせてローカライズします。
• 言語に依存しないスクリーンショット（言語ではなくUIを強調）を優先するか、ロケール別のセットを用意します。
• 図のソースファイル（例：Mermaid）をロケール間で同期させます。
• 画像内の埋め込みテキストは避け、キャプションとラベルを外部化します。

SEOとメタデータ

• タイトル、説明、見出しはロケールに適したキーワードで翻訳します。
• 正規URLと hreflang をサイトのルールに合わせて一貫させます。
• メタ/プロパティキーやJSON-LDのキーを翻訳しないでください。
• 404を避けるため、スラッグをアンカー戦略と整合させます。

ワークフローと自動化

• コードスパンとタグを保持する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