AGENTS.md の次に、翻訳作業を Skills 化してみる

はじめに

前回、Sphinx + ablog で作っている個人技術ノートに AGENTS.md を導入した。

その後、英語ページ向けの .po 翻訳を進める中で、 翻訳作業には毎回同じ確認や判断が多いことに気づいた。

今回は、その翻訳まわりの作業を Codex Skills として切り出してみた記録である。

なぜ翻訳作業を Skills 化するのか

翻訳作業では、単に日本語を英語に置き換えるだけでは済まない。

• msgid は変更しない

• 空の msgstr だけを埋める

• 既存翻訳を不用意に上書きしない

• reStructuredText の記法を壊さない

• rye run doit doc でビルド確認する

• Sphinx の <translated> 警告を見て .po を直す

• 英語として自然な技術ブログ文体にする

これらを毎回 Codex に説明するのは手間がかかる。

また、同じ説明を繰り返すことは、 会話のトークン消費も増やしてしまう。

そこで、翻訳作業専用の手順として Skills にまとめることにした。

AGENTS.md と Skills の役割分担

今回の整理では、AGENTS.md と Skills を次のように分けて考えた。

AGENTS.md には、リポジトリ全体のルールを書く。

• 日本語で説明する

• Rye を使う

• 生成物を直接編集しない

• 記事本文は日本語を正とする

• 英語ページは翻訳版として扱う

一方で、Skills には特定作業の手順を書く。

今回作った sphinx-ablog-translation Skill では、 gettext / sphinx-intl の .po 翻訳作業に必要な判断や確認をまとめた。

作成した Skill

今回作成した Skill は次の場所に置いた。

%USERPROFILE%\.codex\skills\sphinx-ablog-translation

Codex の個人設定配下に置くことで、 このPC上の Codex から利用できるようにする意図である。

リポジトリ配下に置くのではなく、 個人プロファイル側に置くことで、 同じ種類の翻訳作業を他のリポジトリでも使い回しやすくなる。

Skill に含めたもの

最初から翻訳を完全自動化するのではなく、 まずは検査と作業方針を中心にした。

構成は次のようにした。

sphinx-ablog-translation/
  SKILL.md
  references/
    style-guide.md
    glossary.md
  scripts/
    po_status.py
    check_po.py

SKILL.md には、翻訳時の基本ルールを書いた。

• 日本語 .rst を正とする

• msgid は変更しない

• msgstr を埋める

• コマンド、パス、設定名、コード片は保持する

• 翻訳後に rye run doit doc を実行する

• ビルド警告があれば .po の該当箇所を修正する

style-guide.md には、 直訳ではなく自然な英語にするための方針を書いた。

glossary.md には、 この技術ノートでよく出る用語の訳語を置いた。

po_status.py で未翻訳を確認する

po_status.py は、docs/locale/en 配下の .po を確認し、 次の情報を出すためのスクリプトである。

• 構文エラー

• 空の msgstr

• fuzzy

• 翻訳済み件数

今回の確認では、次のような状態まで持っていけた。

files needing work: 0
parse errors: 0
translated entries: 2760/2760

この確認をスクリプトにしたことで、 毎回 Codex に集計用の Python を書かせる必要がなくなる。

check_po.py で rst 記法の崩れを検出する

翻訳作業で特に問題になったのは、 reStructuredText の記法が翻訳によって壊れることだった。

たとえば、次のような記法である。

• インラインリテラルの ``...``

• 強調の **...**

• 脚注参照の [#task]_

• リンク参照の `name`_

• ロールの :doc:`...` や :kbd:`...`

機械翻訳を通すと、引用符やバッククォートが片側だけ変わることがある。 その結果、Sphinx のビルド時に <translated> 警告が出る。

そこで check_po.py では、 翻訳後の msgstr に対して、 壊れやすい記法を検査するようにした。

実際に使ってみた結果

Skill を作る過程で、既存の英訳 .po にもいくつか問題が見つかった。

• msgstr 内の余分な引用符

• ``...`` の閉じ忘れ

• URL付きリンクの消失

• 脚注・参照名の不一致

これらを直したうえで、最終的に次の確認が通った。

files needing work: 0
parse errors: 0
translated entries: 2760/2760
rst markup problems: 0

さらに、rye run doit doc も ja/en ともに成功した。

Skills 化してよかったこと

今回の作業で、Skills は「手順書」と「小さな道具箱」の中間のように使えると感じた。

特によかったのは次の点である。

• 毎回説明していた翻訳ルールを短く呼び出せる

• 集計や検査の Python を毎回生成しなくてよい

• トークン消費を減らしやすい

• 翻訳作業で壊れやすいポイントを蓄積できる

• AGENTS.md を肥大化させずに済む

AGENTS.md はリポジトリ全体の基本方針、 Skills は特定作業の手順と道具、 という分担が見えてきた。

まだ課題もある

一方で、翻訳そのものを完全に自動化するのはまだ慎重にしたい。

機械翻訳で msgstr を一括で埋めることはできるが、 自然な英語になっているか、 技術的に意味がずれていないかは別問題である。

そのため、今回の Skill では、 まず検査と作業方針を中心にした。

翻訳自動化スクリプトを入れるとしても、 既存翻訳を上書きしない、 空の msgstr だけを対象にする、 ビルド警告を必ず確認する、 といった制約が必要だと感じた。

今後の展望

今後は、この Skill を実際の翻訳作業で使いながら育てていきたい。

追加したい候補としては、次のようなものがある。

• 空の msgstr だけを翻訳する補助スクリプト

• Sphinx の警告ログから該当 .po を逆引きするスクリプト

• よくある翻訳崩れの自動修正

• 技術ノート用語集の拡充

• 重要記事だけ人手で英語を磨く運用

まずは、未翻訳確認と rst 記法チェックを安定して使うところから始める。

おわりに

AGENTS.md を導入したことで、リポジトリ全体の作業方針を Codex に伝えやすくなった。

さらに今回、翻訳作業を Skills 化したことで、 特定作業の手順や検査を再利用しやすくなった。

個人技術ノートのように、記事作成、翻訳、ビルド、公開が少しずつ絡み合うリポジトリでは、 こうした小さな Skill を育てていくことが、 作業の安定化と省力化につながりそうである。

記事情報

著者:

mtakagishi

公開日:

2026-05-11

AGENTS.md を既存の Sphinx + ablog 技術ノートに導入する