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 the Phase word in tasks.md,
  • the decision-record status and supersession words, and the lifecycle Status label.

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 without docs.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 init and docguard generate write the marker under each required heading of the documents they create, in English too. With docs.language set to pt or es the heading text is the first alias of the set; for any other language the heading is English and the marker carries the id. A new CHANGELOG.md gets ## [Não lançado] or ## [Sin publicar] plus its marker, and ## [Unreleased] otherwise.
  • docguard generate --plan --write and sync put 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 --write inserts the changelog section as ## [<first alias>] plus the marker.
  • No existing document is rewritten by init or generate.

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.