Skip to content

Adopt halos-docs-tools and the shared translation gate - #29

Draft
mairas wants to merge 2 commits into
mainfrom
feat/shared-translation-workflow
Draft

Adopt halos-docs-tools and the shared translation gate#29
mairas wants to merge 2 commits into
mainfrom
feat/shared-translation-workflow

Conversation

@mairas

@mairas mairas commented Aug 13, 2026

Copy link
Copy Markdown
Contributor

Draft, and it will be red. This repository does not pass the gate yet. Opening it anyway makes the backlog visible rather than leaving it in a survey nobody reads.

The six checkers under scripts/ were copied into four documentation repositories. They now come from halos-org/docs-tools pinned at v0.1.0, and the workflow is the caller stanza for the shared reusable workflow in halos-org/shared-workflows. Unlike the advisory version it replaces, the run goes red when a translation is stale, missing, unstamped or orphaned. It does not block a merge: this repository has no branch protection and no ruleset. See the review synthesis on this PR.

What has to happen before this can merge

docs/en/tutorials/openplotter-server/index.md — 4108 words — has no translation in any of the nine locales, so the gate reports nine missing entries and exits 1. That page entered docs/en/ in 6627593, the commit that set up the translation machinery, and no locale round ever picked it up. The advisory check has been reporting it ever since and nobody acted, which is the argument for a gate that blocks.

Translate it into da de es fi fr it nb nl sv, stamp each with stamp-translation, and this goes green.

What is already verified

mkdocs build --strict is clean and check-anchors site reports all anchors resolving. The gate's only complaint is the nine missing pages, reproduced locally and identical to what CI will report.

The caller deliberately carries no paths filter. A required check that never runs on a pull request touching none of the filtered paths leaves that pull request unmergeable forever.

Same change as hatlabs/halpi2#49, hatlabs/halmet#24 and hatlabs/sh-esp32#20. Part of halos-org/halos#147.

The six checkers move out of scripts/ and into the halos-docs-tools
package, pinned at v0.1.0. The workflow shrinks to the caller stanza for
halos-org/shared-workflows, which runs the same commands and, unlike the
advisory version it replaces, fails the run when a translation is stale,
missing, unstamped or orphaned.

This repository does not pass that gate yet.
docs/en/tutorials/openplotter-server/index.md has no translation in any
of the nine locales. It entered docs/en/ in the commit that set up the
translation machinery and no locale round ever picked it up, which the
advisory check reported and nobody acted on -- the case for a gate that
blocks.

One commit rather than a chain: the old workflow invokes the scripts by
path, so deleting them and repointing CI cannot be separated without an
intermediate commit whose CI is broken.

The Italian glossary contrasted this repository's GLOSSARIES dict with
the HALPI2 repository, where registering the locale used to be a
prerequisite. The dict now lives in the package and carries all nine
locales, so the contrast is gone.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
@github-actions

Copy link
Copy Markdown

Translation status

da — 13 current, 1 missing
de — 13 current, 1 missing
es — 13 current, 1 missing
fi — 13 current, 1 missing
fr — 13 current, 1 missing
it — 13 current, 1 missing
nb — 13 current, 1 missing
nl — 13 current, 1 missing
sv — 13 current, 1 missing

Language Page State Stamp to record
fi tutorials/openplotter-server/index.md missing 3eb95fa3d5c4e946a6ee74c23585b9b432d39c4e
fr tutorials/openplotter-server/index.md missing 3eb95fa3d5c4e946a6ee74c23585b9b432d39c4e
de tutorials/openplotter-server/index.md missing 3eb95fa3d5c4e946a6ee74c23585b9b432d39c4e
sv tutorials/openplotter-server/index.md missing 3eb95fa3d5c4e946a6ee74c23585b9b432d39c4e
es tutorials/openplotter-server/index.md missing 3eb95fa3d5c4e946a6ee74c23585b9b432d39c4e
it tutorials/openplotter-server/index.md missing 3eb95fa3d5c4e946a6ee74c23585b9b432d39c4e
nl tutorials/openplotter-server/index.md missing 3eb95fa3d5c4e946a6ee74c23585b9b432d39c4e
nb tutorials/openplotter-server/index.md missing 3eb95fa3d5c4e946a6ee74c23585b9b432d39c4e
da tutorials/openplotter-server/index.md missing 3eb95fa3d5c4e946a6ee74c23585b9b432d39c4e

The documented pre-flight could not reproduce the gate. The Verifying
block ran `translation-status`, which always exits 0; CI runs
`translation-status --check`. Measured here, where the two disagree
today: plain exits 0, --check exits 1 on the nine missing translations.
A translator following the skill got a clean local run and a red check
-- the same false green this migration exists to remove.

The command rename mangled a path. `../../scripts/check_glossary.py` in
the French glossary became `../../check-glossary`, which points nowhere:
the prefix survived a substitution that removed the file it addressed.
Both entries now name the commands and say where they come from.

deploy.yml holds pages: write and id-token: write and ran plain
`uv sync`, while the gate runs `uv sync --locked`. Now that a git
dependency is in the graph, bumping the pin without re-locking made the
two disagree: the gate refuses, the deploy resolves the new ref live and
runs its build backend with the strongest token in the repository.

Also: the caller stanza states what the called workflow enforces; the
skill says where a new locale gets registered, since the registries are
hardcoded in the package rather than here; the Verifying block said four
and listed five; and the language-selector note named two repositories
and a count of three where four carry the block.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
@mairas

mairas commented Aug 13, 2026

Copy link
Copy Markdown
Contributor Author

Code review — 7 personas, run against the identical change

This PR applies the same change as hatlabs/halpi2#49, so the review ran there. Full synthesis, all 23 findings: hatlabs/halpi2#49 (comment)

Everything that applied here is fixed and pushed in this branch's fix(docs) commit:

  • The documented pre-flight could not reproduce the gate — the Verifying block ran translation-status, which always exits 0, while CI runs translation-status --check.
  • deploy.yml holds pages: write and id-token: write and ran plain uv sync while the gate runs uv sync --locked. With a git dependency in the graph, a pin bumped without re-locking made the two disagree.
  • Deleting the obsolete "register your locale in GLOSSARIES" instructions removed the only pointer to where registration now happens. The skill says so.
  • The caller stanza now states what the called workflow enforces, since the failing command lives in a repository this one does not contain.
  • Smaller: "All four, every time" over a block of five; the language-selector note naming two repositories and a count of three where four carry the block.

Two decisions are still open and they are not mine to make. Both are in the halpi2 synthesis under findings 1, 3 and 4: the gate judges the whole repository while work happens one page at a time, so an English-only edit cannot go green; and no branch protection or ruleset exists on main here, so a red check does not actually block a merge. Merging today leaves the check advisory, which is the option nobody chose.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant