Skip to content

docs: restore the missing accents in the Spanish pages - #511

Open
marevol wants to merge 1 commit into
docs/ds-database-accuracyfrom
docs/es-restore-accents
Open

docs: restore the missing accents in the Spanish pages#511
marevol wants to merge 1 commit into
docs/ds-database-accuracyfrom
docs/es-restore-accents

Conversation

@marevol

@marevol marevol commented Aug 22, 2026

Copy link
Copy Markdown
Contributor

Stacked on #509, because that PR also touches es/.../ds-database.rst. This PR's diff is against it.

Summary

Seven Spanish pages had lost most of their accents. The damage is partial rather
than stylistic - the same page reads Búsqueda in its title and Descripcion
two lines later, índice in one paragraph and indice in the next. It is a
defect, not a house style.

Share of lines carrying an accented character:

Page Before After
config/datastore/ds-database.rst 0.003 0.201
config/datastore/ds-git.rst 0.003 0.129
config/llm-openai.rst 0.015 0.212
config/llm-gemini.rst 0.016 0.189
config/rag-chat.rst 0.029 0.271
config/datastore/ds-slack.rst 0.030 0.176
config/rate-limiting.rst 0.037 0.259

The rest of the Spanish 15.9 set sits between 0.15 and 0.25. These seven were the
only outliers; everything else is above 0.07.

How the spellings were chosen

Not by guessing. Every accented word in the healthy Spanish pages of this
repository
was collected and keyed by its unaccented form. A mapping was kept
only where exactly one accented form existed and the unaccented form is not
itself a Spanish word - 597 substitutions.

Two orthographic rules were applied on top: no Spanish word ends in an unaccented
-cion or -sion, and the plurals -ciones / -siones correctly carry none.

The remaining 121 rare inflected forms and homographs were resolved one at a time
against their context: future and conditional (estaranestarán,
eliminarianeliminarían), preterite (eliminoeliminó, inicio
inició where it is the verb and not the noun), imperative with an enclitic
pronoun (coloquelocolóquelo, AdministrelaAdminístrela), and
adjectives (explicitoexplícito, matematicasmatemáticas).

Homographs left alone

  • que, como, cuando, donde, cual stay unaccented as relatives and
    conjunctions. Only genuine interrogatives were accented: identifica qué paso ha fallado, and the heading Cómo funciona.
  • esta / este stay unaccented as demonstratives; only verb forms became
    está / esté.
  • si stays unaccented as the conditional.
  • solo stays unaccented, per current RAE.
  • envio was split by meaning: envió (verb) at one site, envío (noun) at
    another.

One bulk substitution was wrong and was reverted. Mejora continua
translates "Continuous Improvement", so the adjective is correct there and the
verb continúa is not.

Scope

Prose only, and 15.9 only.

  • 1,645 protected fragments - every literal block body, inline `` span,
    URL and |Fess| substitution - were extracted from both revisions and compared:
    all byte-identical.
  • The diff is 795 insertions against 795 deletions, so no line was added,
    removed or reflowed.
  • Section title underlines are unaffected: an accent does not change a character
    count. tools/check_headings.py passes over all seven languages, as do the
    tools unit tests and update_eol.py --check.

Spanish text inside code blocks was deliberately left as it is - for example the
curl payload in rag-chat.rst:445 still reads explicame como instalar Fess.

Not addressed

  • ds-git.rst:306 uses reindexiza, which is not standard Spanish
    (se reindexa would be). Not an accent problem, so out of scope here.
  • llm-openai.rst and llm-gemini.rst use commita as a verb.
  • Four pre-existing "title underline too short" warnings (rag-chat 1, 29, 601;
    rate-limiting 48) are present identically before and after this change.

Seven Spanish pages had lost most of their accents. The damage was
partial rather than stylistic: the same page reads "Búsqueda" in its
title and "Descripcion" two lines later, "índice" in one paragraph and
"indice" in the next. It is a defect, not a house style.

Measured as the share of lines carrying an accented character, these
seven sat at 0.003 to 0.037 while the rest of the Spanish set sits
between 0.15 and 0.25. They now sit between 0.13 and 0.27.

The correct spellings were not guessed. They were taken from the healthy
Spanish pages in this repository: every accented word in them was
collected, keyed by its unaccented form, and a mapping was kept only
where exactly one accented form existed and the unaccented form is not
itself a Spanish word. That produced 597 substitutions. Two orthographic
rules were applied on top - no Spanish word ends in an unaccented -cion
or -sion, and the plural -ciones/-siones correctly carries none - and the
remaining 121 rare inflected forms and homographs were resolved one by
one against their context.

Homographs were left alone unless the context settled them:

- que, como, cuando, donde, cual stay unaccented as relatives and
  conjunctions; only genuine interrogatives were accented, such as
  "identifica qué paso ha fallado" and the heading "Cómo funciona".
- esta and este stay unaccented as demonstratives; only the verb forms
  became está and esté.
- si stays unaccented as the conditional.
- solo stays unaccented, per current RAE.

One substitution from the bulk pass was wrong and was reverted: "Mejora
continua" translates "Continuous Improvement", so the adjective is
correct there and the verb continúa is not.

Prose only. Every literal block, inline literal, URL and substitution
reference was extracted from both revisions and compared: 1645 protected
fragments, all byte-identical. The diff is 795 insertions against 795
deletions, so no line was added, removed or reflowed, and section title
underlines are unaffected because an accent does not change a character
count.
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