After AGENTS.md, I tried turning translation work into a Skill

Introduction

Previously, I introduced AGENTS.md into my personal technical blog built with Sphinx + ablog.

Later, as I continued translating .po for English pages, I realized that many of the same checks and decisions were made each time I translated.

This post records my attempt to separate that translation workflow into a Codex Skill.

Why turn translation work into a Skill?

Translation work involves more than simply replacing Japanese with English.

• Do not change msgid

• Fill only empty msgstr

• Do not carelessly overwrite existing translations

• Do not break reStructuredText notation

• Check the build with rye run doit doc

• Check Sphinx <translated> warnings and fix the relevant .po entries

• Use natural English technical-blog prose

It takes time to explain these to Codex every time.

Repeating the same explanation also increases token usage in the conversation.

Therefore, I decided to organize them into Skills as procedures dedicated to translation work.

Dividing responsibilities between AGENTS.md and Skills

In this organization, we separated AGENTS.md and Skills as follows.

Use AGENTS.md for repository-wide rules.

• Explain things in Japanese

• Use Rye

• Do not edit generated files directly

• Treat the Japanese article body as the source of truth

• Treat English pages as translated versions

Use Skills for procedures tied to specific tasks.

The sphinx-ablog-translation Skill I created this time summarizes the judgments and confirmations necessary for gettext / sphinx-intl .po translation work.

The Skill I created

I placed the Skill I created this time in the following location.

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

By placing it under Codex’s personal settings, it is intended to be available from Codex on this PC.

By placing it in your personal profile rather than under the repository, it becomes easier to reuse the same type of translation work in other repositories.

What I included in the Skill

Rather than completely automating translation from the beginning, we started by focusing on inspection and work policies.

The configuration was as follows.

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

In SKILL.md, I wrote the basic rules for translation.

• Treat the Japanese .rst as the source of truth

• Do not change msgid

• Fill in msgstr

• Retain commands, paths, configuration names, and code fragments

• Run rye run doit doc after translation

• If there is a build warning, fix the corresponding entry in the .po file

In style-guide.md, I wrote a policy for creating natural English rather than literal translations.

glossary.md contains translations of terms that often appear in this technical note.

Check untranslated entries with po_status.py

po_status.py is a script that checks .po under docs/locale/en and outputs the following information.

• syntax error

• empty msgstr

• fuzzy

• number of translated entries

In this check, I was able to reach the following state.

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

By making this check a script, there is no need to have Codex write Python for aggregation each time.

Detect broken rst markup with check_po.py

A particular problem during the translation process was that the reStructuredText notation was broken by translation.

For example, these forms are easy to break.

• Inline literals written with double backticks

• Emphasis **...**

• [#task]_ in footnote reference

• `name`_ of link reference

• :doc:`...`` and :kbd:`...`` in roles

When passed through machine translation, quotation marks and backticks may change on only one side. As a result, you will receive a <translated> warning when building Sphinx.

Therefore, check_po.py checks the translated msgstr for fragile notations.

Results of actual use

In the process of creating the Skill, we found some problems with the existing English translation .po.

• Extra quotes in msgstr

• Forgetting to close an inline literal

• Loss of links with URLs

• Mismatched footnote/reference name

After correcting these, the following confirmation was finally passed.

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

Furthermore, rye run doit doc was also successful for both ja and en.

What worked well after turning it into a Skill

During this work, I felt that Skills could be used as something between a procedure manual and a small toolbox.

The following points were particularly good.

• You can quickly recall the translation rules that were explained each time.

• No need to generate Python for aggregation or inspection every time

• Easy to reduce token consumption

• You can accumulate fragile points through translation work.

• No need to enlarge AGENTS.md

We can now see a division between AGENTS.md, the basic policy for the entire repository, and Skills, procedures and tools for specific tasks.

There are still challenges

On the other hand, I still want to be cautious about completely automating the translation itself.

It is possible to fill in msgstr all at once with machine translation, but whether it is natural English or whether the meaning is technically correct is another matter.

Therefore, in this Skill, we first focused on inspection and work policy.

Even if I were to include a translation automation script, I felt that restrictions were necessary, such as not overwriting existing translations, targeting only empty msgstr, and always checking for build warnings.

Future plans

In the future, I would like to develop this skill by using it in actual translation work.

Suggestions for additions include the following:

• Auxiliary script that only translates empty msgstr

• A script that reverse looks up the corresponding .po from the Sphinx warning log.

• Automatic correction of common translation errors

• Expansion of technical note glossary

• A workflow for manually polishing only important articles

First, start by using the untranslated confirmation and rst syntax check in a stable manner.

Closing

With the introduction of AGENTS.md, it has become easier to communicate the working policy of the entire repository to Codex.

Furthermore, by converting translation work into skills, it has become easier to reuse procedures and inspections for specific tasks.

In repositories like personal technical notes, where article creation, translation, build, and publication are intertwined little by little, developing these small skills is likely to lead to more stable work and labor savings.

Article information

author:

mtakagishi

Published:

2026-05-11

Adding AGENTS.md to an Existing Sphinx + ablog Technical Note   Export Copilot sessions to record interactions with AI as material for articles