feat(docs): gate the top 10 non-English root-doc locales; germinate French by andrexibiza · Pull Request #80391 · NousResearch/hermes-agent

andrexibiza · 2026-08-06T14:22:01Z

What

Ships the cross-language root-document germination pipeline, with French as the first fully gated locale and one versioned authority for the remaining target set.

Versioned target-locale contract

The canonical target set is the top 10 non-English documentation locales from Ethnologue 200, 29th Edition (2026) using All Users (L1+L2). English is the canonical source graph, not a translation target:

zh-CN, hi, es, ar, fr, bn, pt, id, ur-pk, ru

That distinction keeps both Indonesian and Russian in scope: Russian is 11th in the worldwide table but tenth after canonical English is excluded.

scripts/docs_germination.py now owns the contract through TARGET_LOCALE_CONTRACT, TARGET_LOCALES, and MANIFEST. The conformance suite iterates the canonical tuple directly; it does not maintain a second hardcoded subset.

The manifest also records the existing implementation authorities so this pipeline consolidates work instead of spawning duplicate lanes:

Indonesian: issue [Feature]: Add Indonesian (id) README translation #92191 / implementation PR i18n(id): add Indonesian root documentation trio #92192
Russian: docs: add Russian README translation #69658
Bengali: docs: add Bangla (bn-BD) translation for README #51306
Hindi: feat(docs): Add Hindi (hi) locale to Docusaurus i18n #4763

For every new locale, the contract is the complete README / CONTRIBUTING / SECURITY trio, gate-first, with no manual waiver. manual remains grandfathered debt only for the three translations that predate the pipeline: zh-CN, es, and ur-pk.

The machinery

scripts/docs_germination.py — canonical extract → template → germinate → check pipeline and target-locale manifest.
tests/conformance/test_docs_i18n_germination.py — CI gate for code-fence sequence, backtick technical identifiers, locale-rewritten link targets, resolvable fragments, heading structure, English backlink, and hub discoverability.
docs/developer-guide/docs-i18n-germination-spec.md — portable standard, versioned source contract, runbook, authority map, and measured legacy-debt report.

French

README.fr.md, CONTRIBUTING.fr.md, and SECURITY.fr.md are seeded from @iacker's native translation in #63660, with authorship preserved, then refreshed against current main through the same gate.

The gate has already closed concrete drift in the seed, including missing CLI commands, stale terminal-backend counts, stale test-hook references, malformed fragments, and missing security-model identifiers. This refresh also carries the current hermes --version contract, current Node/workspace installation wording, and current platform-marker guidance.

Legacy debt is measured, not hidden

The existing es, zh-CN, and ur-pk translations run the same checks at warning severity so their drift remains visible in every gate result. New locales cannot use that escape hatch.

Verification

python scripts/docs_germination.py check
bash scripts/run_tests.sh tests/conformance/test_docs_i18n_germination.py

The branch is merged with current main; exact-head CI is the merge authority.

Links

Original issue: Add French translations for README and contributor docs #60535
French seed: docs: add French translations (README, CONTRIBUTING, SECURITY) #63660
Internationalization EPIC: [EPIC] Cross-Language Docs Germination — top-10 non-English target locales, French first #80392
Indonesian authority: [Feature]: Add Indonesian (id) README translation #92191 / i18n(id): add Indonesian root documentation trio #92192

Closes #60535

Part of #80392

Part of #78647

Adds French versions of the core documentation following the existing locale-suffix convention (README.es.md, CONTRIBUTING.es.md, SECURITY.es.md): - README.fr.md - CONTRIBUTING.fr.md - SECURITY.fr.md Translated from the current English sources by a native French speaker. Technical identifiers (commands, paths, env vars, provider/model names, URLs, code blocks) are kept verbatim. The English LICENSE remains the authoritative legal version. Closes NousResearch#60535 Signed-off-by: iacker <iacker@users.noreply.github.com>

Address hermes-sweeper review on NousResearch#63660: - SECURITY.fr.md: point security-policy cross-reference to CONTRIBUTING.fr.md (matching SECURITY.es.md localization convention) - README.md: add README.fr.md language badge so the French translation is discoverable from the primary entry point Signed-off-by: Billard <82095453+iacker@users.noreply.github.com>

The localized-docs drift class, enforced: - scripts/docs_germination.py: the canonical pipeline (extract -> template -> assemble -> check). The parity gate verifies, per locale file against its English source: byte-identical code-fence sequence (code is never translated), verbatim backtick technical identifiers (root-doc names allowed as locale twins), link-target parity under the locale rewrite rule, resolvable internal fragments, heading-level structure parity, locale README back-link, and English-hub discoverability for germinated locales. Manifest carries the top-10 global languages (Ethnologue order) with status and provenance. - tests/conformance/test_docs_i18n_germination.py: behavior contracts (extractor correctness incl. GFM fence-closing rules and unbalanced backtick pairing) plus the gate itself: germinated locales must pass every class; manual/legacy locales (es, zh-CN, ur-pk) report all drift as warnings — debt visible in CI, roadmap to re-germinate. - docs/developer-guide/docs-i18n-germination-spec.md: the portable standard + measured debt report. French (README.fr.md, CONTRIBUTING.fr.md, SECURITY.fr.md) is the first germinated locale; the gate caught real drift in the seed translation (stale backend count, missing commands, stale conftest symbol, drifted security-surface paragraph). Signed-off-by: Andrex Ibiza, MBA <84248988+andrexibiza@users.noreply.github.com>

The cherry-picked French seed (iacker, NousResearch#63660) drifted from the English sources; the germination gate caught each edge and this commit closes the class: - README.fr.md: add missing 'hermes config get' fence line; 'Seven terminal backends' (Vercel Sandbox) — French said six. - CONTRIBUTING.fr.md: restore byte-identical CI comment inside the run_tests.sh fence; fix stale tests/conftest.py::_enforce_test_timeout reference to the real hook tests/conftest.py::pytest_configure; fix two dangling #compétence-ou-outil fragments (github-slugger strips the trailing hyphen). - SECURITY.fr.md: restore the gateway-platform-adapters security-surface paragraph with the plugins/platforms/<name>/ and gateway/platform_registry.py technical identifiers. Translation prose remains iacker's; authorship preserved on the seed commits. The parity gate now passes French with zero errors. Signed-off-by: Andrex Ibiza, MBA <84248988+andrexibiza@users.noreply.github.com>

…unner Completes the pipeline's AUTOMATIC half: the germinate action renders the prose-placeholder template, pipes it to a configured LLM command (stdin->stdout, e.g. 'hermes chat -Q -q'), writes the locale file, and runs the parity gate on the LLM output — the gate is the arbiter, not the model. A translator that drops a technical edge fails the gate and is not shipped. Template hardening discovered by the action's own tests: - HTML badge lines are preserved regardless of leading whitespace. - README templates auto-inject the English language badge (the back-link convention every locale README follows; backlink_parity enforces it). - LLM prompt carries the template with prose markers, hard rules, and DOCUMENT START/END delimiters. Tests: mocked-LLM contracts (no network): write+gate, drift rejection, loud failure on LLM error. Signed-off-by: Andrex Ibiza, MBA <84248988+andrexibiza@users.noreply.github.com>

Signed-off-by: Andrex Ibiza, MBA <84248988+andrexibiza@users.noreply.github.com>

…ent localization Blind semantic review of the French translations (28 findings, zero meaning-changing technical errors) — all applied: - False friend: "éventuellement" -> "en option" (MemoryProvider post_setup). - Calques removed: harnais -> infrastructure de l'agent; plomberie -> infrastructure de configuration; exercez -> testez; amorçage phrasing; "un amont" -> "un service en amont"; "n'opère pas" -> "n'a pas de programme"; sandboxe -> n'isole que le shell. - Meaning shift: "exfiltration opportuniste" -> "exfiltration accidentelle" (casual != opportunistic). - Anglicisms: managé -> géré; template de PR -> gabarit de PR; gating -> verrouillage; Assets TTS -> Ressources TTS; sites d'appel -> points d'appel; "official" -> « officielle ». - Terminology standardized: allowlist -> « liste d'autorisation » everywhere (3 renderings collapsed to 1); "core" -> « cœur ». - Residual English: reload/start-chatting comments, skill-example comments, branch-type table, version-window comments, tree-structure comments, project-tree comments — all translated. - Recurring calque: "résoudre des approbations" -> « statuer sur les approbations » (3 sites). Gate refinement enabling this: fence comments are now LOCALIZABLE prose — comment-normalized body hashes (commands must match exactly, comments may be translated, comment code spans like `env -i` still required). This is the principled line: code never translated, comments are docs. chore: map contributor email iacker (credit ledger for NousResearch#63660 seed). Signed-off-by: Andrex Ibiza, MBA <84248988+andrexibiza@users.noreply.github.com>

andrexibiza · 2026-08-06T19:31:26Z

The long-document production skill and the canonical publication are now proposed in #80551.

This contribution is interlocked with the graph-gated engineering family:

Part of Repo-wide godfile eradication: residual 2K tasks after #102117 #78647
Related feat(skills): add the large-file decomposition feature package skill (5x2x3 blind-witness decomposition) #79609 (godfile-kill-campaigns)
Related docs(skills): document the kill-locks feature package and its tracker interlock #79779 (campaign-operations-kill-locks)
Related feat(skills): add the feature-parity-alignment skill (5x2x3 parity Feature Package playbook) #79898 (Feature Parity & Alignment campaigns)
Related feat(docs): gate the top 10 non-English root-doc locales; germinate French #80391 (cross-language docs germination)
Related [EPIC] Cross-Language Docs Germination — top-10 non-English target locales, French first #80392 (cross-language docs germination EPIC)
Related Add French translations for README and contributor docs #60535 / docs: add French translations (README, CONTRIBUTING, SECURITY) #63660 (French provenance and contributor authorship)

The repository contribution includes the skill under skills/research/, the guide under website/docs/guides/, the guide sidebar and llms.txt generator registration, the compiled 68-page PDF, LaTeX source, BibTeX, and a checked-in bidirectional interlock manifest.

Attribution is a core value: the contribution preserves Axl Ibiza, MBA’s authorship of the doctrine and publication, plus contributor, reviewer, agent, and source-project provenance.

PR: #80551
Signed-off-by: Andrex Ibiza, MBA 84248988+andrexibiza@users.noreply.github.com

spfcraze · 2026-08-08T01:38:42Z

This was generated by AI during triage.

Summary:
The gate's top-10 completeness test asserts fr plus the eight codes zh-CN, hi, es, ar, bn, pt, ru, ur-pk, and the manifest comment labels id "next in line after the top-10" although id sits inside TOP_10_LANGUAGES.

Problems:

test_manifest_covers_top_ten_languages_and_french asserts fr and the eight codes zh-CN, hi, es, ar, bn, pt, ru, ur-pk; TOP_10_LANGUAGES has ten members, so the assertion loop and the tuple it is meant to check cover different sets.
The "id" entry is annotated "Indonesian (next in line after the top-10)" inside TOP_10_LANGUAGES, whose module comment describes it as the top-10 roadmap and whose PR body lists id as the tenth of ten — the inline comment and the tuple disagree about id's membership.

Solution:
Have the test iterate TOP_10_LANGUAGES directly instead of a hardcoded subset, and reword the "id" comment to match its position in the tuple, so the manifest, the gate, and the docs agree on the top-10 set.

Checked against 41a78cd — the tip of docs/i18n-germination when this was written.

ahliweb · 2026-08-23T11:55:25Z

Indonesian lane update — #92192 is now in the required full-trio shape

Following the authoritative decisions recorded in #80392, I have updated the existing Indonesian implementation PR #92192 in place (no duplicate PR):

README.id.md
CONTRIBUTING.id.md
SECURITY.id.md
README badge-hub parity across the existing localized READMEs

The old divergent branch state was preserved in a backup ref, then #92192 was rebuilt from current upstream history and synchronized with main. Current #92192 head: 9e6769f4326c91ce10dae5ed355d238570b9868e.

Current repository state for #92192:

open
mergeable
exactly 7 documentation files changed
2026 / 29th-Edition non-English target-locale contract reflected in the PR description
merge explicitly blocked pending the corrected feat(docs): gate the top 10 non-English root-doc locales; germinate French #80391 gate and green CI

This makes #80391 the remaining authoritative dependency for the Indonesian lane. Per #80392, please carry the agreed corrections here before the gate is used for #92192:

version the target contract as top 10 non-English locales using Ethnologue 200, 29th Edition / 2026, All Users (L1+L2);
remove the contradictory id “11th / next in line” annotations;
make the completeness test iterate the canonical target-locale constant directly;
bind [Feature]: Add Indonesian (id) README translation #92191 / i18n(id): add Indonesian root documentation trio #92192 as the claimed Indonesian implementation in the manifest;
keep ru in scope because English is canonical source, not a translation target.

Once an updated gate head is available, I can validate/fix the Indonesian trio against that exact gate before merge.

Part of #80392
Related #92191
Related #92192

ahliweb · 2026-08-26T12:30:18Z

Indonesian root-doc lane synchronized to current main

The Indonesian implementation authority #92192 has now been synchronized to current upstream main (dcfdc8deec3c5918fc55be8807cb7e307417f91e) without rewriting translation content.

Current #92192 head: d9e94ee31fac4705b660d24ebbff8a994ab8d2ca

0 commits behind current main;
merge base is current main;
exactly the intended 7 documentation files remain in scope;
i18n(id): add Indonesian root documentation trio #92192 is currently mergeable;
fresh CI / Nix / Docker runs are action_required, not executed failures.

A collision review over the 232 upstream commits since the previous synchronization found no changes to canonical README.md, CONTRIBUTING.md, or SECURITY.md, so no Indonesian semantic refresh was needed.

#80391 remains the procedural blocker for #92192 because this gate is still open and currently not mergeable. Once the gate is synchronized/fixed and authoritative, #92192 can be validated against that exact gate head before maintainer merge.

andrexibiza · 2026-08-31T17:41:13Z

CI repair pushed — `34c6c1c33fe0`

Removed the unmatched standalone fence in CONTRIBUTING.md; the exact baseline failed two French parity tests, while the repaired tree reports 0 errors from docs_germination.py check and 25/25 conformance tests passing. No French document, germination code, or test was changed.

This is an append-only fast-forward from 3ee89248a661 to 34c6c1c33fe0. Current GitHub checks have been triggered; I will bind the final exact-head result here after they settle.

andrexibiza · 2026-08-31T17:50:08Z

Exact-head CI closeout — `34c6c1c33fe0`

The unmatched CONTRIBUTING.md fence is gone. The repaired docs graph reports 0 germination errors and the focused conformance file passes 25/25; French content, parser code, and tests remain unchanged.

GitHub now reports the current exact-head check set successful and the PR merge state clean. Contributor-side implementation, verification, and push commentary are closed at 34c6c1c33fe0d1494a7f430673c9b36ff7d3e405.

iacker and others added 6 commits August 6, 2026 08:47

docs(i18n): document the germinate action in the germination spec

c7089d4

Signed-off-by: Andrex Ibiza, MBA <84248988+andrexibiza@users.noreply.github.com>

This was referenced Aug 6, 2026

[EPIC] Cross-Language Docs Germination — top-10 non-English target locales, French first #80392

Open

docs: add French translations (README, CONTRIBUTING, SECURITY) #63660

Closed

alt-glitch added type/docs Documentation improvements P3 Low — cosmetic, nice to have area/i18n Localization, locales, translations sweeper:risk-automation Sweeper risk: may affect CI, automerge, label sync, or maintainer automation labels Aug 6, 2026

andrexibiza mentioned this pull request Aug 21, 2026

[Architecture / Publication] Task Completion Verification — exact-object completion as the sixth Hermes law #91230

Open

42 tasks

ahliweb mentioned this pull request Aug 23, 2026

i18n(id): add Indonesian root documentation trio #92192

Open

andrexibiza added 6 commits August 23, 2026 07:30

docs(i18n): version the non-English target-locale contract

757c9e5

fix(i18n): bind the versioned non-English locale manifest

1dcefa8

test(i18n): derive completeness from the canonical locale tuple

4e8f81f

merge(main): refresh docs germination branch onto current main

f8eea6f

docs(i18n): restore French discoverability on current main

6f43b40

docs(i18n): refresh French security version command

d5440d4

docs(i18n): refresh French contributing graph against current main

c885fe3

andrexibiza changed the title ~~feat(docs): cross-language docs germination pipeline — French automatic, top-10 languages manifest, CI gate~~ feat(docs): gate the top 10 non-English root-doc locales; germinate French Aug 23, 2026

merge(main): synchronize docs germination with current main

3ee8924

andrexibiza mentioned this pull request Aug 25, 2026

[Architecture] Hermes Authority Execution Layer — the twelve issues are one defect, and the architecture that fixes it #95028

Open

fix(docs): remove unmatched contributing fence

34c6c1c

Navigation Menu

Uh oh!

feat(docs): gate the top 10 non-English root-doc locales; germinate French - #80391

feat(docs): gate the top 10 non-English root-doc locales; germinate French#80391
andrexibiza wants to merge 16 commits into
NousResearch:mainfrom
andrexibiza:docs/i18n-germination

andrexibiza commented Aug 6, 2026 •

edited

Loading

Uh oh!

andrexibiza commented Aug 6, 2026

Uh oh!

spfcraze commented Aug 8, 2026

Uh oh!

ahliweb commented Aug 23, 2026

Uh oh!

ahliweb commented Aug 26, 2026

Uh oh!

andrexibiza commented Aug 31, 2026

Uh oh!

andrexibiza commented Aug 31, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

5 participants

Uh oh!

Conversation

andrexibiza commented Aug 6, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

What

Versioned target-locale contract

The machinery

French

Legacy debt is measured, not hidden

Verification

Links

Uh oh!

andrexibiza commented Aug 6, 2026

Uh oh!

spfcraze commented Aug 8, 2026

Uh oh!

ahliweb commented Aug 23, 2026

Indonesian lane update — #92192 is now in the required full-trio shape

Uh oh!

ahliweb commented Aug 26, 2026

Indonesian root-doc lane synchronized to current main

Uh oh!

andrexibiza commented Aug 31, 2026

CI repair pushed — 34c6c1c33fe0

Uh oh!

andrexibiza commented Aug 31, 2026

Exact-head CI closeout — 34c6c1c33fe0

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

5 participants

andrexibiza commented Aug 6, 2026 •

edited

Loading

CI repair pushed — `34c6c1c33fe0`

Exact-head CI closeout — `34c6c1c33fe0`