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 non-blank lines carrying an accented character (áéíóúüñ, upper case,
¿¡):

Page Before After
config/datastore/ds-git.rst 0.005 0.195
config/datastore/ds-database.rst 0.017 0.271
config/llm-openai.rst 0.021 0.310
config/llm-gemini.rst 0.022 0.290
config/rag-chat.rst 0.040 0.386
config/datastore/ds-slack.rst 0.042 0.260
config/rate-limiting.rst 0.052 0.378

Measured the same way, the other 140 pages of es/15.9 run from 0.057 to 0.694
with a median of 0.296, and the only one below 0.09 is admin/index.rst, which
is almost entirely a toctree. These seven were the outliers.

(ds-database.rst starts at 0.017 rather than near zero only because the text
#509 adds to it is already accented.)

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 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,079 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 782 insertions against 782 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 the versions versions.json calls
    current, 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 still reads explicame como instalar Fess, and
the placeholder `datastore://<id de la configuracion...>` in
ds-database.rst keeps its spelling because it sits inside an inline literal.

Not addressed

  • ds-git.rst 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, rate-limiting)
    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 between 0.004 and 0.037 while the rest of the Spanish set sits
between 0.15 and 0.25. They now sit between 0.14 and 0.29.

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 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: 1079 protected
fragments, all byte-identical. The diff is 782 insertions against 782
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