Repository navigation
Docs written in another language: required headings, changelog marker, decision status and text metrics assume English #644
Description
Summary
DocGuard 0.47.0 runs cleanly on documentation written in Portuguese: no errors, and FR-001 style requirement ids inside Portuguese sentences are recognized with file and line. But every structural label it looks for must be in English. A team that writes its docs in another language gets warnings it cannot clear without switching those labels to English, and in a strict setup (warnings as failures) they block.
Measured with a throwaway project, once with DocGuard's own headings left in English and once with them translated.
What happens
| Input | Result |
|---|---|
| Portuguese prose with accents inside sections | Works, no finding |
FR-001 inside a Portuguese sentence |
Recognized |
## Visão geral do sistema in place of ## System Overview (same for Tech Stack, Component Map, Test Categories, Coverage Rules) |
Warning per section: missing section "## System Overview" |
A spec with ## Requisitos funcionais and ## Feito quando |
Warnings: missing mandatory section User Scenarios, Requirements, Success Criteria; no SC-001 ids found |
## [Não lançado] in CHANGELOG.md |
Warning: missing [Unreleased] section |
**Status:** Aceito in a decision record |
Warning: status "Aceito" is not proposed, accepted, rejected, deprecated or superseded |
| Text-quality metrics (passive voice, negation, conditional, compound requirement) | The patterns are English word lists (doc-quality.mjs), so the numbers are not meaningful for non-English text, and nothing says so |
Minimal reproduction
mkdir ptbr && cd ptbr && git init -q
mkdir -p src docs/adr specs/001-exemplo
echo 'export function soma(a, b) { return a + b; }' > src/soma.js
echo '{"name":"ptbr","version":"0.1.0","type":"module"}' > package.json
docguard init --yes && docguard generate --plan --writeThen translate the generated ## headings in docs-canonical/ARCHITECTURE.md and docs-canonical/TEST-SPEC.md, add a spec whose sections are ## Problema, ## Requisitos funcionais (with FR-001), ## Feito quando, add docs/adr/0001-exemplo.md with **Status:** Aceito, and run docguard guard --format json.
Observed: WARN, 0 errors, with the warnings in the table above. With the English headings restored and Spec ID, User Scenarios & Testing, Requirements, Success Criteria and SC- ids used in the spec, the section warnings disappear while the body stays in Portuguese.
Workaround today
Keep the structural labels in English and write everything else in the team's language. It works, but it has to be discovered by trial.
Suggested changes
- Heading synonyms per language. A
language(orheadingAliases) setting in.docguard.json, with built-in sets for pt-BR and es to start, so## Visão geral do sistemasatisfiesSystem Overview. The existing<!-- docguard:section system-overview … -->marker suggests an id-based anchor would also work: accept<!-- docguard:section system-overview -->under a heading in any language. - Spec sections. The same aliases for the Spec Kit mandatory sections.
- Changelog marker. Accept a configured or aliased equivalent of
[Unreleased]. - Decision status. Extend
SYNONYMindecision-records.mjswith translated status words (aceito,proposto,rejeitado,obsoleto,substituído, and the Spanish forms), or make the map configurable. - Text metrics. Detect or accept the document language, and when the word lists do not cover it, skip those metrics and say they were skipped instead of reporting a number.
- Docs. Until then, one paragraph in the README (and in
README.pt-BR.md/README.es.md) stating which labels must stay in English.
Environment
DocGuard 0.47.0, Node, macOS. Not tested: WebSec Validator and TestGuard with non-English docs.
Activity
raccioly commentedon Nov 12, 2026
Triage: confirmed against the code, and accepted. Every row in the table matches what 0.47.0 does.
One thing the code adds to the report: the heading matcher normalizes a heading by keeping only
a-z0-9(normalizeHeadingTextincli/shared.mjs), so accented letters are dropped before any comparison.Visão geralbecomesvis o geral. Translated synonyms alone would not match until that normalization handles Unicode letters.Planned shape, to be written as its own spec after the strict-by-default work (#637) lands, because both touch the same validators:
<!-- docguard:section system-overview -->under a heading in any language satisfies the required section. No word list, works for every language, and the generators can write the id.headingAliasessetting for others, with Unicode-aware normalization.FR-/SC-ids already work in any language.[Unreleased], and translated decision-status words.languagesetting (or detection), a metric whose word list does not cover the language reports "not measured" with the reason, never a number. This is the same rule spec(097): strict by default #637 applies to validators: a check that examined nothing must not read as a result.Item 6 (say in the READMEs which labels must stay in English) is being done now as a documentation-only PR.
docs: say which labels must stay in English in the three READMEs (#647)
spec(104): measure the Test-Spec row against an English control
spec(104): record the maintainer's decisions on the open questions
spec(104): documents in any language (issue 644) (#690)
fix(sections): a section marker without id= opens no bounded block (s…