From 4a251d4b9c724a5bd3dd75f7c91c6aae77c6650e Mon Sep 17 00:00:00 2001 From: JoaoAugusto00 <128641539+JoaoAugusto00@users.noreply.github.com> Date: Sun, 18 Oct 2026 05:57:46 -0300 Subject: [PATCH] docs: how to install spelling dictionaries (pt_BR example) (#2510) Co-authored-by: Brandon Thomas --- README.md | 4 +- docs/localization-parity.md | 6 +- docs/spelling-dictionaries.md | 125 ++++++++++++++++++++++++++++++++++ 3 files changed, 133 insertions(+), 2 deletions(-) create mode 100644 docs/spelling-dictionaries.md diff --git a/README.md b/README.md index 3d0d44afc..41b097cbd 100644 --- a/README.md +++ b/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. diff --git a/docs/localization-parity.md b/docs/localization-parity.md index d2289fabf..7e635759a 100644 --- a/docs/localization-parity.md +++ b/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) | diff --git a/docs/spelling-dictionaries.md b/docs/spelling-dictionaries.md new file mode 100644 index 000000000..180ac4cb6 --- /dev/null +++ b/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 `.aff` and +`.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 |