Documents in Other Languages
DocGuard reads documentation written in any language. The structural labels it looks for are matched by id, not by English text, so a project that writes its documents in Portuguese, Spanish or any other language does not need English headings. This page is the reference: the closed list of ids, the marker, the built-in sets, how to extend them, what is skipped and why, and what is still open.
What is a label, and what is not
A label is a structural word DocGuard has to find to judge a document:
- the required headings of the canonical documents (
ARCHITECTURE.md,DATA-MODEL.md,SECURITY.md,TEST-SPEC.md,ENVIRONMENT.md) and the Test-Spec source-to-test map, - the README’s Installation, Usage and License sections,
- the changelog’s unreleased section,
- the Spec Kit section names (
spec.md,plan.md, the bugfix shape) and thePhaseword intasks.md, - the decision-record status and supersession words, and the lifecycle
Statuslabel.
Everything else stays language-neutral and is not a label: prose, requirement ids (FR-001, SC-001, REQ-001), task ids (T001), the Spec ID, the docguard:spec-type marker and every other docguard: marker. Spec Kit’s own templates stay English and specify is untouched; DocGuard never rewrites a Spec Kit template.
The ids
Every id below is a heading (a marker may name it) or a word (matched by alias only; there is no marker for a status word). The list is closed: an unknown id in a marker is STR009, and an unknown id in docs.labelAliases is reported and ignored. The table is generated from cli/shared-labels.mjs; docguard explain STR009 prints the same ids.
| Id | Kind | Marker | English | pt | es |
|---|---|---|---|---|---|
system-overview | heading | <!-- docguard:heading system-overview --> | System Overview | Visão geral do sistema, Visão geral, Panorama do sistema | Visión general del sistema, Descripción general del sistema, Visión general, Resumen del sistema |
component-map | heading | <!-- docguard:heading component-map --> | Component Map | Mapa de componentes, Componentes | Mapa de componentes, Componentes |
tech-stack | heading | <!-- docguard:heading tech-stack --> | Tech Stack | Stack tecnológica, Pilha tecnológica, Stack tecnológico, Stack de tecnologia, Tecnologias, Tecnologias utilizadas | Stack tecnológico, Pila tecnológica, Tecnologías, Tecnologías utilizadas |
layer-boundaries | heading | <!-- docguard:heading layer-boundaries --> | Layer Boundaries | Limites entre camadas, Camadas, Fronteiras entre camadas | Límites entre capas, Capas |
data-flow | heading | <!-- docguard:heading data-flow --> | Data Flow | Fluxo de dados | Flujo de datos |
external-dependencies | heading | <!-- docguard:heading external-dependencies --> | External Dependencies | Dependências externas | Dependencias externas |
revision-history | heading | <!-- docguard:heading revision-history --> | Revision History | Histórico de revisões, Histórico de alterações | Historial de revisiones, Historial de cambios |
entities | heading | <!-- docguard:heading entities --> | Entities | Entidades, Modelo de dados | Entidades, Modelo de datos |
relationships | heading | <!-- docguard:heading relationships --> | Relationships | Relacionamentos, Relações | Relaciones |
indexes | heading | <!-- docguard:heading indexes --> | Indexes | Índices | Índices |
authentication | heading | <!-- docguard:heading authentication --> | Authentication | Autenticação | Autenticación |
secrets-management | heading | <!-- docguard:heading secrets-management --> | Secrets Management | Gerenciamento de segredos, Gestão de segredos, Gestão de credenciais | Gestión de secretos, Manejo de secretos |
authorization | heading | <!-- docguard:heading authorization --> | Authorization | Autorização | Autorización |
security-boundaries | heading | <!-- docguard:heading security-boundaries --> | Security Boundaries | Limites de segurança, Fronteiras de segurança | Límites de seguridad |
test-categories | heading | <!-- docguard:heading test-categories --> | Test Categories | Categorias de teste, Categorias de testes, Tipos de teste, Tipos de testes | Categorías de pruebas, Tipos de pruebas |
coverage-rules | heading | <!-- docguard:heading coverage-rules --> | Coverage Rules | Regras de cobertura | Reglas de cobertura |
test-commands | heading | <!-- docguard:heading test-commands --> | Test Commands | Comandos de teste, Comandos de testes | Comandos de prueba, Comandos de pruebas |
source-to-test-map | heading | <!-- docguard:heading source-to-test-map --> | Source-to-Test Map, Service-to-Test Map | Mapa de código para testes, Mapa de fontes para testes, Mapa do código-fonte para testes | Mapa de código a pruebas, Mapa de código fuente a pruebas |
environment-variables | heading | <!-- docguard:heading environment-variables --> | Environment Variables | Variáveis de ambiente | Variables de entorno |
setup-steps | heading | <!-- docguard:heading setup-steps --> | Setup Steps | Passos de configuração, Instalação e configuração, Como configurar, Configuração | Pasos de configuración, Instalación y configuración, Configuración |
prerequisites | heading | <!-- docguard:heading prerequisites --> | Prerequisites | Pré-requisitos | Requisitos previos, Prerrequisitos |
configuration-files | heading | <!-- docguard:heading configuration-files --> | Configuration Files | Arquivos de configuração, Ficheiros de configuração | Archivos de configuración |
installation | heading | <!-- docguard:heading installation --> | Installation | Instalação | Instalación |
usage | heading | <!-- docguard:heading usage --> | Usage | Uso, Como usar, Utilização | Uso, Cómo usar |
license | heading | <!-- docguard:heading license --> | License, Licence | Licença | Licencia |
contributing | heading | <!-- docguard:heading contributing --> | Contributing | Contribuindo, Como contribuir, Contribuição, Contribuições | Contribuir, Cómo contribuir, Contribuciones |
user-scenarios | heading | <!-- docguard:heading user-scenarios --> | User Scenarios | Cenários de usuário, Histórias de usuário, Cenários e testes, Cenários de usuário e testes, Cenários de uso | Escenarios de usuario, Historias de usuario, Escenarios de uso, Escenarios de usuario y pruebas |
requirements | heading | <!-- docguard:heading requirements --> | Requirements | Requisitos, Requisitos funcionais | Requisitos, Requisitos funcionales |
success-criteria | heading | <!-- docguard:heading success-criteria --> | Success Criteria | Critérios de sucesso, Critérios de aceite, Critérios de aceitação | Criterios de éxito, Criterios de aceptación |
summary | heading | <!-- docguard:heading summary --> | Summary | Resumo | Resumen |
technical-context | heading | <!-- docguard:heading technical-context --> | Technical Context | Contexto técnico | Contexto técnico |
project-structure | heading | <!-- docguard:heading project-structure --> | Project Structure | Estrutura do projeto | Estructura del proyecto |
phase | word | none | Phase | Fase | Fase |
root-cause | heading | <!-- docguard:heading root-cause --> | Root Cause | Causa raiz | Causa raíz |
fix | heading | <!-- docguard:heading fix --> | Fix | Correção, Solução | Corrección, Solución |
unreleased | heading | <!-- docguard:heading unreleased --> | Unreleased | Não lançado, Não publicado | Sin publicar, No publicado, Por publicar |
proposed | word | none | proposed | proposto, proposta, rascunho, em análise | propuesto, propuesta, borrador |
accepted | word | none | accepted | aceito, aceita, aprovado, aprovada | aceptado, aceptada, aprobado, aprobada |
rejected | word | none | rejected | rejeitado, rejeitada, recusado, recusada | rechazado, rechazada |
deprecated | word | none | deprecated | obsoleto, descontinuado, depreciado, obsoleta, descontinuada | obsoleto, en desuso, deprecado, obsoleta |
superseded | word | none | superseded | substituído, substituída, superado, superada | sustituido, sustituida, reemplazado, superado, reemplazada, superada |
supersedes | word | none | Supersedes | Substitui | Sustituye, Reemplaza |
superseded-by | word | none | Superseded by | Substituído por, Substituída por | Sustituido por, Reemplazado por, Sustituida por |
lifecycle-status | word | none | Status | Status, Situação, Estado | Estado |
The n/a marker for a section that does not apply uses the same ids: <!-- docguard:section authentication n/a — CLI, no auth -->.
The heading marker
## Visão geral do sistema
<!-- docguard:heading system-overview -->
Texto.
- The marker is the next non-blank line under the heading, outside a code fence and outside any larger comment. Anywhere else it is ignored and reported as STR009 (misplaced).
- It names an id; the heading text can be anything in any language, and the heading keeps the text, and the anchor, the author wrote.
- A marker is explicit, so it works in every language and in a project with no
docs.language. It is the only new behavior withoutdocs.language. - When the marker and the heading’s text disagree (the heading is the English label of another id), the marker wins and STR009 says so.
- An HTML comment is invisible in GitHub, GitLab and every CommonMark renderer.
Built-in sets: pt and es
Set docs.language in .docguard.json to a BCP 47 tag:
{ "docs": { "language": "pt-BR" } }
A tag is matched by its primary subtag: pt-BR and pt-PT use the pt set, es-MX uses es. The sets are the table above. Matching folds case and accents (Visao geral matches Visão geral), compares whole headings, and drops a leading section number (5.4 Camadas matches Camadas). English is always accepted, in every language, so mixed documents work. With docs.language absent or "en" the matching is the English matching it has always been, byte for byte. An invalid tag is reported and treated as absent.
The headings and words of the pt and es sets were reviewed by a native speaker on 2026-11-17, and so were the prose word lists behind the text metrics (task T033, see below). A heading that is missing from a set is never a dead end: the marker always works.
Your own wording: docs.labelAliases
{
"docs": {
"language": "pt-BR",
"labelAliases": {
"requirements": ["Requisitos do sistema"],
"accepted": ["Vigente"]
}
}
}
Keys are ids from the table; each value is a list of strings. Project aliases extend the built-in sets and never replace them. A front-matter status: in a decision record goes through the same aliases. Aliases are read only when docs.language is set.
A language with no built-in set
Any other valid tag ("de", "fr", "ja") is accepted and has no built-in set. DocGuard cannot tell a missing section from one written in that language, so a required heading that has no English form, no marker and no docs.labelAliases entry does not produce a missing-section finding (STR003 and its siblings). The document is listed under “DocGuard could not read” in guard, and in strict.couldNotRead in guard --format json, with the cause language-not-supported, the language and the fix. That entry never changes the exit code. Add a marker or an alias and the entry disappears.
Documents named by language
With docs.language set, a document’s own name can say it is in another language: README.pt-BR.md, docs-canonical/ARCHITECTURE.pt-BR.md, or a file under i18n/pt-BR/ or locales/pt-BR/. Its labels resolve with that language’s set and its text metrics are measured or skipped as for that language. The language is never inferred from the text, and without docs.language nothing is inferred.
What is skipped, and why
A check that cannot judge a document because of its language says so instead of passing silently or inventing a number.
| Check | In a language other than English |
|---|---|
| Passive voice (DQ001), Flesch Reading Ease and Flesch-Kincaid (DQ004, DQ005) | Skipped: the rules are English grammar. Reported with the reason language-not-supported; no number, no finding, not counted in the score. |
| Negation (DQ007), conditional (DQ008), compound requirement (DQ003), ambiguous pronouns (DQ002) | Run for pt (pt-BR, pt-PT) and es (every es-*) with the word lists a native speaker reviewed on 2026-11-17 (see below), and with the same thresholds as English. Skipped for every other language, with the reason language-not-supported. |
| Sentence length (DQ006) | Runs where the script separates words with spaces; skipped for zh, ja, th, lo, km, my. |
| Docs-Diff’s tech stack, Metrics-Consistency, semantic claims | Report language-not-supported for the documents they would have read. |
Agent-instruction files (AGENTS.md, CLAUDE.md, …) and the instruction audit | Out of scope: they get no alias and no language-not-supported entry. |
The tokenizer and the sentence splitter are Unicode-aware for a non-English docs.language (não is one word) and unchanged for English.
What the writers do
docguard initanddocguard generatewrite the marker under each required heading of the documents they create, in English too. Withdocs.languageset toptoresthe heading text is the first alias of the set; for any other language the heading is English and the marker carries the id. A newCHANGELOG.mdgets## [Não lançado]or## [Sin publicar]plus its marker, and## [Unreleased]otherwise.docguard generate --plan --writeandsyncput a generated block under the heading that already holds the section, in any accepted form. When no heading exists they write the first alias plus the marker, never an English heading into a translated document, and for a language with no set they write the block without a heading and report it.docguard fix --writeinserts the changelog section as## [<first alias>]plus the marker.- No existing document is rewritten by
initorgenerate.
Word lists for the text metrics (pt and es)
Negation (DQ007), conditional (DQ008), ambiguous pronouns (DQ002) and compound sentences (DQ003) count words of a closed list per language. The Portuguese and Spanish lists were reviewed by a native speaker on 2026-11-17 (task T033 of spec 104) and live in one module, cli/shared-prose-words.mjs. A word is matched whole, ignoring case, with accents optional in the text (nao counts as não) but never invented: é is not the conjunction e, sí (“yes”) is not si (“if”), and él counts only with its accent because el is the article. A hyphen between letters belongs to the word, so e-mail, não-funcional and configura-se never match e, não or se. A phrase matches across spaces. The thresholds are the English ones: pronouns over 15% of the words, compound sentences over 35% of the sentences, negation over 20%, conditionals over 30%. <!-- docguard:quality negation-load off — reason --> works as in English.
| Metric | Portuguese (pt) | Spanish (es) |
|---|---|---|
| Negation | não, nunca, jamais, nenhum, nenhuma, nenhuns, nenhumas, nem, ninguém, nada, tampouco | no, nunca, jamás, ningún, ninguno, ninguna, ningunos, ningunas, ni, nadie, nada, tampoco |
| Conditional | se (see below), caso, quando, sempre que, a menos que, a não ser que, salvo se, exceto se, contanto que, desde que, somente se, apenas se, só se, até que, caso contrário, senão | si (without the accent), cuando, siempre que, a menos que, salvo que, excepto si, en caso de, en caso de que, con tal de que, solo si, sólo si, hasta que, de lo contrario, si no |
| Ambiguous pronouns | isso, isto, aquilo, ele, ela, eles, elas, este, esta, estes, estas, esse, essa, esses, essas, seu, sua, seus, suas, dele, dela, deles, delas | esto, eso, aquello, él (with the accent), ella, ellos, ellas, este, esta, estos, estas, ese, esa, esos, esas, su, sus |
| Non-atomic sentence | e também, e depois, e então, assim como, bem como, além de, além disso, adicionalmente, ademais, outrossim, or two or more “e” in one sentence | y también, y luego, y después, así como, además de, además, adicionalmente, asimismo, a su vez, or two or more “y” or “e” in one sentence |
Portuguese se is also the reflexive pronoun (o arquivo se encontra, configura-se), which is far more common in technical text than the conditional, so it counts only as the first word of a sentence or right after a comma, and never after a hyphen. This misses some conditionals in the middle of a sentence, which is the safer side. desde que is counted as “provided that”; its time sense (“since”) is less common in requirement-style text.
Left out on purpose: sem and sin (“without”; English does not count it either), enquanto and mientras (mostly temporal), the articles and clitics o a os as lhe and lo la los las le les, el without the accent, and sí with it. Portuguese often omits the subject pronoun, so its pronoun share runs lower than in English; the threshold stays. A correction to a list is an issue or a pull request.
Open
Passive voice and the two Flesch scores stay skipped for every language but English: their rules are English grammar and syllables. Every other language keeps sentence length only, and a language other than pt and es has no reviewed word lists, so the four metrics above are skipped, not guessed. The heading and word sets are data: a correction is an issue or a pull request, and the marker and docs.labelAliases work meanwhile.