translate

name	translate
description	docs/en/配下の英語ドキュメント(.py jupytext形式)をdocs/ja/に日本語翻訳する。翻訳ルールとワークフローを定義。

英日翻訳スキル

docs/en/配下の英語ドキュメントをdocs/ja/に翻訳する。引数で対象ファイルパスを受け取る（例: /translate docs/en/release_notes/v0_10_0.py）。

ワークフロー

0. docs/README.mdを読む。docs build/testの最新ルールはそこをsource of truthにする。
1. docs/en/側の対象.pyファイルを読む。
2. docs/ja/側に対応するディレクトリがなければ作成する。
3. 以下の翻訳ルールに従って.pyファイルを翻訳・作成する。既存のMarkdown構造、見出し階層、セル順、コードブロック、表、リストは原則としてEN側と同じ形に保つ。翻訳時にskeletonを当て直したり、ページ構成を再設計したりしない。
4. 対応する.ipynbを更新する。安全に実行できる通常ページなら./docs/build.sh page-build docs/ja/<section>/<file>.pyを使い、.py→.ipynb同期、notebook実行、JA docs buildをまとめて行う。API keyやremote side effectが必要なページでは、必要なcredentialがない限り実行せず、uv run jupytext --to ipynb --update docs/ja/<section>/<file>.pyでpaired notebookだけ同期する。
5. 既存の通常セクション（tutorial/、algorithm/、usage/、integration/）へ翻訳を追加・更新するだけなら、docs/ja/myst.ymlは触らない。TOCはpattern: <section>/*.ipynbで自動発見される。myst.ymlを更新するのは、新しいトップレベルsectionや、release notesのように明示childrenで管理されている例外だけ。
6. 対応するindex.mdは、JA側に存在しない新しいsectionを作る場合や、新規翻訳ページを読者に見せるためsection indexの記事リスト更新が必要な場合だけ作成・更新する。

既訳がある場合（更新・差分再翻訳）: 対象ファイルがすでにdocs/ja/に存在する場合は、新規翻訳ではなく更新になる。その場合はステップ3の前に ルール10 に従って「EN側が前回同期から何を変えたか」を全部洗い出すこと。新しく足されたセクションだけを訳して、その変更が前方の表・intro・まとめに与えた波及を訳し漏らすと、JA内部で矛盾が残る。

翻訳ルール

1. 文体

• ニュートラルな「です・ます」調を使う。カジュアルすぎる表現は避ける。
  • × 「処理してくれます」 → ○ 「処理をします」
  • × 「取得してもらえます」 → ○ 「取得できます」
• 直訳より意訳を優先し、自然な日本語を目指す。

2. スペーシング

• 日本語と英数字の間にスペースを入れない。 英単語(クラス名、用語、コードコメント中の語など)が日本語文中に登場する場合も同じ。
  • × 「Qamomile は量子 SDK です」
  • ○ 「Qamomileは量子SDKです」
  • × 「親が consume される前に」
  • ○ 「親がconsumeされる前に」
  • × 「view が live な間」
  • ○ 「viewがliveな間」

3. 技術用語の扱い

• 広く認知されている英語の技術用語はカタカナ化せず英語のまま残す。
  • × 「エグゼキュータ」 → ○ 「Executor」
  • × 「トランスパイラ」は許容（日本語圏で定着しているため）
• 判断基準: その用語がAPIやクラス名としてコード中に出現する場合は英語のまま。日本語技術文書で一般的にカタカナで使われている場合（トランスパイル、デコレータなど）はカタカナでもよい。
• モード名・機能を表す英語の形容詞は英語のまま、かつ表記を統一する: concrete / symbolic(mode)、active、target、pool、prefix のように、対応するソースやチュートリアルで英語表記される語はカタカナ化しない(「シンボリック」「アクティブ」等にしない)。同一ドキュメント内で英語形とカタカナ形を混在させない(片方が symbolic、別の箇所が「シンボリック」のような揺れを残さない)。迷ったら対応する docs/ja/ のチュートリアル(例: tutorial/04_controlled_gates)の表記に合わせる。
• Qamomile固有の語の訳語統一(本文・見出し・コメント。コード識別子は対象外):
  • 英語の kernel / sub-kernel(@qmc.qkernel を指すもの)は 「量子カーネル」 に統一する。「カーネル」「サブカーネル」とは書かない(kernel と sub-kernel の区別は日本語では落とし、どちらも「量子カーネル」)。qkernel / @qmc.qkernel のようなコード語そのものは英語のまま。
  • pool / register の文脈の slot は 「量子ビット」 と訳す。「スロット」とは書かない。
  • 本文中の英単語 qubit も 「量子ビット」 に統一する(「制御qubit」「1qubit」「qubit数」のような英語表記を本文に混在させない)。ただし型名・コード語の Qubit / Vector[Qubit] / qmc.Qubit / qmc.qubit / qmc.qubit_array は英語のまま(大文字 Qubit や .qubit を巻き込まないこと)。同一ファイル内で「qubit」と「量子ビット」が揺れていたら「量子ビット」に寄せる。
  • 注意: これらは本文中の語の置換であって、case_pool_slot_as_target のような Python 識別子や文字列ラベルの中の slot / kernel / qubit は置換しない(コードは英語のまま)。一括置換するとコード識別子まで巻き込むので、置換対象を本文・コメントに限定すること。

4. 簡潔さ

• 冗長な修飾を避ける。主語や目的語が文脈から明らかな場合は省略する。
  • × 「これらの推定値は入力パラメータの…」
  • ○ 「これらは入力パラメータの…」

5. 原文への忠実さ

• 原文のニュアンスを正確に伝える。機械的な逐語訳ではなく、意味を汲み取って日本語として自然な表現にする。
  • 原文 "so you can analyze how resources scale" → × 「スケーリングを解析できます」 → ○ 「スケーリングの解析が容易です」
• 原文に暗黙的な情報（時点、前提条件など）がある場合は、読者のために補足してよい。
  • 例: 「量子フーリエ変換（QFT）や…が含まれます」→「現在量子フーリエ変換（QFT）や…が含まれます」
• APIやConverterを主語にした英文は、直訳で「〜は…を実装します」と書くと不自然になりやすい。読者ができることを主語にして訳す。
  • × 「FooConverterは、問題に対してFoo Encodingを実装します」
  • ○ 「FooConverterを使うと、問題にFoo Encodingを適用できます」
  • ○ 「FooConverterは、問題にFoo Encodingを適用するためのAPIです」
• user-facing docsでは、内部実装の語をそのまま前面に出さない。特に「束縛する」「address resolution」「path」「fallback」のような語は、読者から見える挙動に言い換える。
  • × 「qmc.expvalがobservableを正しい物理量子ビットに束縛するようになりました」
  • ○ 「Vector要素に対するqmc.expvalの挙動を修正しました」
  • × 「conditionのaddress resolutionを修正しました」
  • ○ 「測定結果を使う条件分岐が正しいclassical bitアドレスへloweringされるようになりました」
• release noteのバグ修正では、内部語よりも読者に見える症状と結果を優先する。必要以上に細かいbackend分岐や実装経路をoverviewに入れず、詳細は本文の該当bulletへ寄せる。
• 量子ビット数削減・高速化・再現性などの効果は、原文の "can" / "may" / "can reduce" などの限定を保つ。常に成り立つように読める断定にしない。
• release noteでは、一般語としての「コンパイル」はなるべく避ける。Qamomileの変換処理が焦点なら「トランスパイル時」、より広い現象なら「エラーになることがありました」「扱えるようになりました」のように具体的な症状や結果で書く。
• "less brittle"や"more robust"を機械的に「壊れにくい」と訳さない。修正の意図に応じて「サポート範囲を広げました」「より多くのケースを扱えるようになりました」「挙動を修正しました」のように、読者に見える変化を書く。
• 機能改善は「扱います」よりも「扱えるようになりました」「できるようになりました」を優先する。既存機能の説明なら「扱います」でもよいが、release noteで「now support」「can now」などの差分を表す場合は改善後の可能性を明示する。
  • × 「より多くのqmc.control(...)パターンをend-to-endで扱います」
  • ○ 「より多くのqmc.control(...)パターンをend-to-endで扱えるようになりました」

6. コードブロックとコメント

• コードのフォーマットは英語版と同一に保つ。 改行位置やインデントを変えない。
• コード中のコメントは日本語に訳す。
• pip installなどのコマンドやコード内の英語コメント（# CUDA-Q with CUDA 12.x等）はそのまま残す。

7. リンクとMarkdown構造

• Markdownの構造（見出しレベル、リスト、テーブル）は英語版と一致させる。
• チュートリアルなどへのリンクテキストは日本語に訳す。
• URLパスはそのまま維持する。

8. 区切り記号(em dash「—」とコロン「:」)

英語で多用される —(em dash)と :(コロンで導入する書き方)は、そのまま訳出すると日本語では不自然になります。意訳して自然な接続詞・句点・接続表現に置き換えてください。

em dash「—」

• × 「親Vectorは対象のスロットをviewに貸し出します — スロットを返却するまでは…」
• ○ 「親Vectorは対象のスロットをviewに貸し出します。スロットを返却するまでは…」
• ○ 「親Vectorは対象のスロットをviewに貸し出すため、スロットを返却するまでは…」

文意に応じて句点で切る、接続詞(「ただし」「つまり」「すなわち」「そのため」など)で繋ぐ、あるいは関係を明示する構文に書き換えます。原文の — の前後の関係(同格・対比・補足・帰結など)を読み取り、それに合った日本語表現を選んでください。

コロン「:」で導入する書き方

英語の「Sentence: detail」というパターンを「文:詳細」とそのまま訳すと不自然です。「〜には、…」「〜は次の通りで、…」のような自然な接続にします。

• × 「修正は機械的です:借りたものを同じ形で返します」
• ○ 「修正方法は単純で、借りたものを同じ形で返すだけです」
• ○ 「これを直すには、借りたものを同じ形で返します」

ただし、リストや手順を導入する場合のコロン(「次の点に注意してください:」)、コード例を導入するコロンは残してよい。

9. ぼやけた前段+「すなわち」の言い換え

英語によくある vague phrase, namely / i.e., specific thing のパターンを「ぼやけた前置きすなわち具体例」とそのまま訳すと、日本語では一文がくどく読みづらくなります。前置きを薄くする・短い文に切る・例を直接出すなど、平易な日本語表現に書き換えてください。

• × 「本章では、関連はしているが別の構成要素を扱います。qmc.controlを使って、任意のゲート、すなわちqmc.rxのようなビルトインゲートやユーザ定義の@qmc.qkernelを、それ自体の制御版に変換する方法です。」
• ○ 「本章ではqmc.controlを扱います。qmc.controlを使うと、Qamomileの任意のゲート(qmc.rxのようなビルトイン関数や、ユーザが書いた@qmc.qkernel)の制御版を作れます。」

英語の related but distinct building block: turning X — namely Y — into Z のような「メタな枠付け+すなわち+具体」 を、 日本語では「本章ではXを扱います。Xを使うと、Y(例えば…)はZになります。」 のように 2 文以上に分けて、 抽象的な前置きを薄くするのが基本方針です。 「すなわち」 自体を機械的に避ける必要はありませんが、 ぼやけた前置きの後ろで具体例を挙げる接続として使うのは避けてください。

同じ理由で「related but distinct」「entirely different but related」のような英語の挿入句も、日本語では削るか別の文に分けます。

• × 「これは関連はしているが別の概念であり、…」
• ○ 「これとは別の概念で、…」/ 「これは似ていますが別の概念です。…」

10. 既訳の更新（差分再翻訳）時はEN全差分を訳し、JA全体の整合性を確認する

すでにdocs/ja/側に訳が存在するドキュメントを、EN側の更新に追随して訳し直すときは、「変更の主題になっているセクション」だけを訳すのではなく、そのEN更新が触れた全hunkを訳す。機能追加のcommitは、新セクションを足すと同時に、それと矛盾しないよう前方の表・intro・まとめ・相互参照も書き換えていることが多い。これらの散らばった編集を見落とすと、新しく訳したセクションと古いままの前方セクションが食い違う「部分再翻訳ドリフト」が起きる。

実際に起きた例: EN側がsymbolic modeにmulti-arg制御prefixを追加したcommitは、新しい§5.5を足すと同時に§2の表・§3 introの「symbolicはpoolを1つだけ」という記述も「single-poolまたはmulti-arg」に書き換えていた。しかしJA側の追随翻訳は§5.5だけを訳して§2/§3の修正を訳し漏らし、JAだけが「poolを1つだけ」という旧主張を残してしまった。

手順:

1. JAが最後にENと同期された時点を特定する（git log --oneline -- docs/en/<path>とdocs/ja/<path>を見比べる）。そこから現在までのEN差分をgit diff <old>..HEAD -- docs/en/<path>で全部出す。
2. その差分のすべてのhunkに対応するJA更新を行う。新セクションの追加だけでなく、既存セクションの1行修正・表セルの書き換え・cross-referenceの更新も漏らさない。
3. 訳し終えたらJAドキュメント全体を通読し、内部整合性を確認する。新しく訳したセクションの主張と矛盾する記述が前方に残っていないか。特に「Xだけ」「ちょうど1つ」「〜できない」「〜専用」のような断定・排他の表現は、後から入った機能で無効化されやすいので重点的に確認する。

11. 人工改行の扱い

• 英語版のMarkdownテキスト行内の改行（soft line break）は、日本語版では結合して1行にする。
  • jupytextでnotebookに変換すると改行が半角スペースになるため、日本語では不自然な空白が生じる。
  • 英語版:

    # Hello, this is
    # me
    

  • 日本語版:

    # こんにちは，わたしです
    

  • コードブロック内の改行はこのルールの対象外（ルール6に従う）。