docs: how to install spelling dictionaries (pt_BR example) (#2510)

Co-authored-by: Brandon Thomas <echelon@gmail.com>

README.md

@@ -366,7 +366,9 @@ Bundled fonts, icons, images and other assets keep their own open licenses; each
 with its author, source and license in [ATTRIBUTION.md](ATTRIBUTION.md).
 
 The English spelling dictionary and hyphenation come from Grady Ward's public-domain Moby
-Hyphenator II word list. Polish spelling reads the Hunspell `pl_PL` dictionary installed on the system (not bundled) and
+Hyphenator II word list. Polish spelling reads the Hunspell `pl_PL` dictionary installed on the system (not bundled), as
+do Russian, Portuguese, Czech, Italian, Croatian and Turkish spelling (how to install them:
+[docs/spelling-dictionaries.md](docs/spelling-dictionaries.md)), and
 Polish hyphenation the TeX patterns by Hanna Kołodziejska, Bogusław Jackowski and Marek Ryćko (MIT
 option). The sample documents and templates are original text written for WordCraft.
 

docs/localization-parity.md

@@ -1,6 +1,6 @@
 # Localization parity with Microsoft Word
 
-> **Last reviewed:** 2026-10-10 · **Last updated:** 2026-10-16 · **Change:** minor (Read Aloud speaks each sentence in its own language, #1843; previously minor: Indonesian proofing: id-ID spelling from the installed Hunspell dictionary, dictionary-driven suggestions, generic checks with Indonesian messages, #498; previously trivial: print-area strings translated in every catalog; previously trivial: Italian: the interface audit checks the Italian catalog, `Privacy Settings` wording; previously trivial: Italian grammar: `po'`, `qual è`, `È`, `un`/`un'` rules; more elisions and truncations in spelling; previously trivial: Czech interface catalog completed, 2,447 entries; previously trivial: interface audit runs in CI again: size labels translated, 20 strings in every catalog, Read Aloud error race fixed, #1128; previously trivial: Review › Language reaches every language again — Set Proofing Language… and Set As Default, #860; previously minor: Italian proofing: it-IT spelling from the installed Hunspell dictionary, accent-first suggestions, conservative grammar with Italian messages; previously minor: Portuguese proofing; previously trivial: Turkish interface catalog completed, 2,325 entries, #774; previously minor: Hungarian interface added; previously trivial: sorting and table numbers follow the text's language, #836, #837; previously minor: Polish interface; Polish proofing — spelling, grammar, hyphenation — and a proofing language per run; previously minor: Turkish interface added; previously major: first version; catalogs measured from `crates/ui-egui/src/i18n`, Word's languages from its bundle listing) · **Target:** Microsoft Word (Microsoft 365) for Mac 16.113.4
+> **Last reviewed:** 2026-10-10 · **Last updated:** 2026-10-16 · **Change:** minor (how to install the Hunspell dictionaries on Windows, macOS and Linux: `docs/spelling-dictionaries.md`; previously minor: Read Aloud speaks each sentence in its own language, #1843; previously minor: Indonesian proofing: id-ID spelling from the installed Hunspell dictionary, dictionary-driven suggestions, generic checks with Indonesian messages, #498; previously trivial: print-area strings translated in every catalog; previously trivial: Italian: the interface audit checks the Italian catalog, `Privacy Settings` wording; previously trivial: Italian grammar: `po'`, `qual è`, `È`, `un`/`un'` rules; more elisions and truncations in spelling; previously trivial: Czech interface catalog completed, 2,447 entries; previously trivial: interface audit runs in CI again: size labels translated, 20 strings in every catalog, Read Aloud error race fixed, #1128; previously trivial: Review › Language reaches every language again — Set Proofing Language… and Set As Default, #860; previously minor: Italian proofing: it-IT spelling from the installed Hunspell dictionary, accent-first suggestions, conservative grammar with Italian messages; previously minor: Portuguese proofing; previously trivial: Turkish interface catalog completed, 2,325 entries, #774; previously minor: Hungarian interface added; previously trivial: sorting and table numbers follow the text's language, #836, #837; previously minor: Polish interface; Polish proofing — spelling, grammar, hyphenation — and a proofing language per run; previously minor: Turkish interface added; previously major: first version; catalogs measured from `crates/ui-egui/src/i18n`, Word's languages from its bundle listing) · **Target:** Microsoft Word (Microsoft 365) for Mac 16.113.4
 
 Interface languages, script support and proofing per language. How translation works (catalog
 format, adding a language, clean-room rule): `crates/ui-egui/src/i18n/mod.rs`.
@@ -113,6 +113,9 @@ other than envelopes (Letter, Legal, A4, B5 (JIS)) stay as they are (#1128).
 | Indonesian (`id`, `id-ID`, `ind`, legacy `in`) | The system Hunspell `id_ID` dictionary, read at runtime (Debian/Ubuntu: `hunspell-id`; LibreOffice's `dict-id`; the same system, LibreOffice, Dictionaries folder and `WORDCRAFT_DICTIONARIES` search paths as Polish). No dictionary data is bundled; without an installed dictionary spelling stays off. Hyphenated reduplication is accepted whole (`kupu-kupu`) or by parts (`anak-anak`); hyphenated clitics after capitals and abbreviations (`KTP-nya`, `se-Indonesia`) are accepted | the same dictionary-driven ranking as Czech: MAP/REP/TRY/KEY tables of the loaded dictionary, missing spaces and a stem scan; nothing Indonesian hard-coded | Indonesian messages for repeated words (offering the hyphenated reduplication `anak-anak` first, then the single word), space before punctuation and double spaces only; no Indonesian-specific grammar rules | existing English fallback, as for `Other`; no Indonesian patterns bundled |
 | Any other | — (no marks) | — | — | the English patterns, as before |
 
+The dictionary file names each language looks for, the folders searched on each system and how to
+install one (`pt_BR` as the example): [spelling-dictionaries.md](spelling-dictionaries.md).
+
 Measured with the SJP.PL dictionary: every one of the ~4.5 million forms an independent expansion of its affix file
 produces is accepted, and 200,000 one-edit mutations that aren't words are all rejected; a check
 takes ~1 µs, a suggestion list 1–35 ms (release build). Not yet: Czech hyphenation patterns or Czech-specific grammar, other languages' dictionaries,
@@ -195,6 +198,7 @@ WordCraft keeps 2,54 cm).
 |---|---|---|
 | 2026-10-16 | minor | Indonesian proofing (#498): id-ID spelling from the installed Hunspell `id_ID` dictionary (not bundled), Czech's dictionary-driven suggestions, repeated-word (hyphenated reduplication offered) and spacing checks with Indonesian messages; Review › Language, the status bar, Set Proofing Language and File › Options › Proofing list Indonesian; estimates unchanged |
 | 2026-10-16 | trivial | Read Aloud picks a voice for the sentence's language (run tag, else script) when the default voice doesn't speak it, reads Windows text as UTF-8 |
+| 2026-10-16 | trivial | Linked the new guide to installing the Hunspell dictionaries on Windows, macOS and Linux (`docs/spelling-dictionaries.md`, `pt_BR` as the example); estimates unchanged |
 | 2026-10-12 | minor | Czech proofing review: short-word splits rank after deletion, NOSUGGEST excludes suggestions while accepting typed forms, affix comments apply only to headers, ratios keep spaces and repeated-word messages use Czech quotes; synthetic engine end-to-end and latency checks |
 | 2026-10-12 | minor | Czech spelling from the installed Hunspell dictionary, runtime-table suggestions and generic checks; Czech interface writes cs-CZ documents; no Czech hyphenation patterns bundled; estimates unchanged |
 | 2026-10-13 | minor | Swedish interface catalog (2,504 entries), locale selection, saved preference, audit coverage and font checks (#1219) |

docs/spelling-dictionaries.md

@@ -0,0 +1,125 @@
+# Installing spelling dictionaries
+
+> **Last reviewed:** 2026-10-16 · **Last updated:** 2026-10-16 · **Change:** major (first version)
+
+English spelling works out of the box. Polish, Russian, Portuguese, Czech, Italian, Croatian and
+Turkish spelling use a standard **Hunspell** dictionary (an `.aff` and a `.dic` file) that
+WordCraft reads at runtime. These dictionaries are not bundled: they are large, and several are
+GPL or LGPL licensed. Without one, the language isn't checked. The status bar then shows the
+language with **(no dictionary)**, for example *Português (Brasil) (no dictionary)*.
+
+Install a dictionary once, restart WordCraft, and the language is checked as you type.
+
+## Which files each language needs
+
+WordCraft looks for the first of these file names (each name means a `<name>.aff` and
+`<name>.dic` pair in the same folder):
+
+| Language | File names | Common source |
+|---|---|---|
+| Polish | `pl_PL`, `pl-PL`, `pl` | SJP.PL |
+| Russian | `ru_RU`, `ru-RU`, `ru` | LibreOffice `dict-ru` |
+| Portuguese (Brazil and Portugal) | `pt_BR`, `pt-BR`, `pt` | VERO (LibreOffice `dict-pt-BR`) |
+| Czech | `cs_CZ`, `cs-CZ`, `cs` | LibreOffice `dict-cs` |
+| Italian | `it_IT`, `it_CH`, `it-IT`, `it` | LibreOffice `dict-it` |
+| Croatian | `hr_HR`, `hr-HR`, `hr` | LibreOffice `dict-hr` |
+| Turkish | `tr_TR`, `tr-TR`, `tr` | LibreOffice `dict-tr` |
+
+Every Portuguese region uses the same `pt_BR` dictionary, so text marked *Português (Portugal)*
+is checked with it too.
+
+The files may be UTF-8 or the encoding named on the `.aff`'s `SET` line (ISO 8859-2, KOI8-R and
+Windows-1251 are read as well).
+
+## Where WordCraft looks
+
+The first folder holding a matching pair wins:
+
+1. The folder set in **File › Options › Proofing › Dictionaries folder**. This is the easiest
+   way on every system, and it works for an app started from the Start menu, Finder or the Dock.
+   The same pane lists the dictionary file each language found.
+2. The folder in the `WORDCRAFT_DICTIONARIES` environment variable.
+3. The system's usual places:
+
+| System | Folders |
+|---|---|
+| Windows | `%LOCALAPPDATA%\WordCraft\dictionaries`, `%LOCALAPPDATA%\hunspell`, `%APPDATA%\WordCraft\dictionaries`, `%APPDATA%\hunspell`, LibreOffice's `share\extensions\dict-*` under `Program Files` (on any drive) |
+| macOS | `~/Library/Spelling`, `/Library/Spelling`, `/opt/homebrew/share/hunspell`, `/usr/local/share/hunspell`, `/Applications/LibreOffice.app/Contents/Resources/extensions/dict-*` |
+| Linux and BSD | `~/.local/share/hunspell`, `/usr/share/hunspell`, `/usr/share/myspell`, `/usr/share/myspell/dicts`, `/usr/local/share/hunspell`, `/usr/local/share/myspell`, LibreOffice's `share/extensions/dict-*` under `/usr/lib/libreoffice` or `/opt/libreoffice` |
+
+The web version can't read these folders, so these languages aren't spell-checked there.
+
+## Example: Brazilian Portuguese (`pt_BR`)
+
+VERO, the Brazilian Portuguese dictionary LibreOffice ships, is available from the
+[LibreOffice dictionaries repository](https://github.com/LibreOffice/dictionaries/tree/master/pt_BR)
+(LGPLv3 / MPL). Any of these ways works.
+
+### If LibreOffice is installed
+
+Nothing to do: WordCraft finds LibreOffice's `dict-pt-BR` extension on its own. Restart
+WordCraft after installing LibreOffice.
+
+### Windows
+
+In PowerShell:
+
+```powershell
+$d = "$env:LOCALAPPDATA\WordCraft\dictionaries"
+New-Item -ItemType Directory -Force $d | Out-Null
+$base = "https://raw.githubusercontent.com/LibreOffice/dictionaries/master/pt_BR"
+Invoke-WebRequest "$base/pt_BR.aff" -OutFile "$d\pt_BR.aff" -UseBasicParsing
+Invoke-WebRequest "$base/pt_BR.dic" -OutFile "$d\pt_BR.dic" -UseBasicParsing
+```
+
+### macOS
+
+```sh
+mkdir -p ~/Library/Spelling
+cd ~/Library/Spelling
+curl -fLO https://raw.githubusercontent.com/LibreOffice/dictionaries/master/pt_BR/pt_BR.aff
+curl -fLO https://raw.githubusercontent.com/LibreOffice/dictionaries/master/pt_BR/pt_BR.dic
+```
+
+### Linux
+
+From the distribution's packages:
+
+```sh
+sudo apt install hunspell-pt-br   # Debian, Ubuntu
+```
+
+Or, without root, into your own folder:
+
+```sh
+mkdir -p ~/.local/share/hunspell
+cd ~/.local/share/hunspell
+curl -fLO https://raw.githubusercontent.com/LibreOffice/dictionaries/master/pt_BR/pt_BR.aff
+curl -fLO https://raw.githubusercontent.com/LibreOffice/dictionaries/master/pt_BR/pt_BR.dic
+```
+
+Other languages work the same way: replace `pt_BR` with the language's folder and file names
+from the LibreOffice repository (for example `it_IT/it_IT.aff`).
+
+## Checking that it works
+
+- Restart WordCraft. The status bar no longer says **(no dictionary)**, and a misspelled word
+  such as `impramir` is underlined, with `imprimir` among its suggestions.
+- **File › Options › Proofing** lists the file each language found.
+- From the command line:
+
+  ```sh
+  wordcraft-cli run --cmd 'text.insert={"text":"Vou impramir o documento."}' --cmd select.all --cmd 'review.language={"lang":"pt-BR"}' --cmd review.issues --print
+  ```
+
+  The `review.issues` line lists `impramir` as a spelling issue with its suggestions.
+- The log file (`%APPDATA%\WordCraft\logs\wordcraft.log` on Windows) says
+  `Portuguese spelling: no Hunspell pt_BR dictionary installed` when none was found.
+
+Never commit dictionary files to this repository: they stay on the user's system.
+
+## Revision history
+
+| Date | Change | Summary |
+|---|---|---|
+| 2026-10-16 | major | First version: the file names per language, the search order and folders on Windows, macOS and Linux, installing `pt_BR` on each, and how to check it works |