hunspell(5)

💖 hunspell(5) 💖

okay bestie, welcome to hunspell(5) — the format of Hunspell dictionaries and affix files. this is the lore for how hunspell(1) does its thing. no cap, we're keeping every detail. 💅

✨ NAME ✨

hunspell — format of Hunspell dictionaries and affix files

🌸 DESCRIPTION 🌸

okay so hunspell(1) needs two files to define how a language gets spell-checked: a dictionary file with words and applicable flags, and an affix file that says how those flags control spell checking. the personal dictionary file is an optional third file. periodt.

🦋 Dictionary file 🦋

A dictionary file (*.dic) is literally a list of words, one per line. the first line of a dictionary (except personal dictionaries) has the approximate word count (for optimal hash memory size). each word may optionally be followed by a slash ("/") and one or more flags, which represent the word's attributes (for example, affixes). 💖

The slash separates the word from its flags, so it's the first unescaped slash on the line that marks the end of the word. a word may itself contain a slash if the slash is escaped as "\/". 🫶

A slash in the very first column is part of the word, not a separator. a line such as "/foo" is the whole word "/foo" with no flags. to give a word that starts with a slash some flags, write a second slash before the flags, as in "/foo/X". a leading slash followed by other text and no later slash, such as "/ comment text", is therefore loaded as one literal word and never expands into flagged forms. 😭

It is worth adding not only individual words but also word pairs to the dictionary, to get correct suggestions for common misspellings that are missing a space, as in the following example for the bad "alot" and "inspite" (see also "REP" and the "ph:" field for correct suggestions for common misspellings):

3
word
a lot
in spite

🎀 Personal dictionary file 🎀

Personal dictionaries are simple word lists. an asterisk in the first character position marks the entry as forbidden. a second word separated by a slash sets the affixation: it names an existing dictionary word, and the new word is then recognized with the same affixes as that word. the text after the slash is an example word, not the affix class flags used in the main dictionary .dic file. 👑

foo
Foo/Simpson
*bar

In this example, "foo" and "Foo" are personal words, plus Foo will be recognized with affixes of Simpson (Foo's etc.) and bar is a forbidden word. 💀

🌈 Short example 🌈

Dictionary file:

3
hello
try/B
work/AB

The flags B and A specify attributes of these words.

Affix file:

SET UTF-8
TRY esianrtolcdugmphbyfvkwzESIANRTOLCDUGMPHBYFVKWZ'

REP 2
REP f ph
REP ph f

PFX A Y 1
PFX A 0 re .

SFX B Y 2
SFX B 0 ed [^y]
SFX B y ied y

In the affix file, prefix A and suffix B have been defined. flag A defines a re- prefix. class B defines two -ed suffixes. first B suffix can be added to a word if the last character of the word isn't y. second suffix can be added to the words terminated with an y. ✨

All accepted words with this dictionary and affix combination are: "hello", "try", "tried", "work", "worked", "rework", "reworked". 🔥

👑 AFFIX FILE GENERAL OPTIONS 👑

Hunspell source distribution contains more than 80 examples for option usage. not me reading all of them... okay actually yes, bestie, we list them. 💅

🌸 SET encoding 🌸

Set character encoding of words and morphemes in affix and dictionary files. possible values: UTF-8, ISO8859-1 - ISO8859-10, ISO8859-13 - ISO8859-15, KOI8-R, KOI8-U, cp1251, ISCII-DEVANAGARI. 🦋

SET UTF-8

🌸 FLAG value 🌸

Set flag type. default type is the extended ASCII (8-bit) character. UTF-8 parameter sets UTF-8 encoded Unicode character flags. the long value sets the double extended ASCII character flag type; the num value sets the decimal number flag type. decimal flags are numbered from 1 to 65000 and are separated by commas in flag fields. long flags have no separator, so the flag field AaBb holds the two flags Aa and Bb. 💖

FLAG long

🌸 COMPLEXPREFIXES 🌸

Set twofold prefix matching, but only one suffix level instead of the default two. set it when words take two stacked prefixes. this is common in agglutinative languages written right to left, but any language that stacks prefixes can use it. 🫶

🌸 LANG langcode 🌸

Set language code for language-specific functions of Hunspell. use it to activate special casing of Azeri (LANG az), Turkish (LANG tr) and Crimean Tatar (LANG crh), and the non-generalized syllable-counting compounding rules of Hungarian (LANG hu). 👑

🌸 IGNORE characters 🌸

Set characters to ignore in dictionary words, affixes and input words. useful for optional characters such as Arabic (harakat) or Hebrew (niqqud) diacritical marks (see the tests/ignore.* test dictionary in the Hunspell distribution). 😭

🌸 AF number_of_flag_vector_aliases 🌸

🌸 AF flag_vector 🌸

Hunspell can substitute affix flag sets with ordinal numbers in affix rules (alias compression, see makealias tool). first example with alias compression:

3
hello
try/1
work/2

AF definitions in the affix file:

AF 2
AF A
AF AB

It is equivalent to the following dic file:

3
hello
try/A
work/AB

See also tests/alias* examples of the source distribution.

Note I: if the affix file contains the FLAG parameter, define it before the AF definitions.

Note II: use the makealias utility in the Hunspell distribution to compress aff and dic files.

🌸 AM number_of_morphological_aliases 🌸

🌸 AM morphological_fields 🌸

Hunspell can also substitute morphological data with ordinal numbers in affix rules (alias compression). see tests/alias* examples.

✨ AFFIX FILE OPTIONS FOR SUGGESTION ✨

Okay so this whole section is about making Hunspell's suggestions hit different. 💅 The suggestion parameters can optimize Hunspell's default n-gram (that's a similarity search through the dictionary words based on common 1-, 2-, 3-, and 4-character sequences, iykyk), plus character-swap and deletion suggestions.

REP is the moment for fixing typical and especially bad language-specific spelling errors, because REP suggestions have the highest priority in the suggestion list. And PHONE is for languages whose orthography is not pronunciation-based.

For short common misspellings, it's important to use the ph: field (see later) to give the best suggestions.

---

💫 KEY

• KEY characters_separated_by_vertical_line_optionally — Hunspell searches for and suggests words in which a single character has been replaced by a neighbouring KEY character. Non-neighbouring characters in the KEY string are separated by vertical line characters. Suggested KEY parameters for QWERTY and Dvorak keyboard layouts:

KEY qwertyuiop|asdfghjkl|zxcvbnm
KEY pyfgcrl|aeouidhtns|qjkxbmwvz

Using the first QWERTY layout, Hunspell suggests "nude" and "node" for "*nide". A character may have more neighbors, too:

KEY qwertzuop|yxcvbnm|qaw|say|wse|dsx|sy|edr|fdc|dx|rft|gfv|fc|tgz|hgb|gv|zhu|jhn|hb|uji|kjm|jn|iko|lkm

🎀 TRY

• TRY characters — Hunspell can suggest correct word forms when they differ from the bad input word by one TRY character. The parameter of TRY is case-sensitive.

For example, take a dictionary that contains the word "work" and the bad input word "wark". Hunspell tries to fix the word by replacing each letter in turn with each character listed in TRY. With

TRY o

replacing the "a" with "o" produces "work", so "work" is suggested. With

TRY i

the letter "o" is never tried, so "work" is never produced and there is no suggestion. The list should therefore hold the characters of the language, most frequent first, so that likely corrections are found. 👑

🦋 NOSUGGEST

• NOSUGGEST flag — Words flagged with NOSUGGEST are not suggested (but are still accepted when typed correctly). Proposed for vulgar and obscene words (see also SUBSTANDARD).

🌸 MAXCPDSUGS

• MAXCPDSUGS num — Set the maximum number of suggested compound words generated by compound rules. The number of suggested compound words from the same 1-character-distance type may exceed this.

✨ MAXNGRAMSUGS

• MAXNGRAMSUGS num — Set the maximum number of n-gram suggestions. A value of 0 switches off n-gram suggestions (see also MAXDIFF).

💜 MAXDIFF

• MAXDIFF [0-10] — Set the similarity factor for the n-gram based suggestions (5 = default value; 0 = fewer n-gram suggestions, but min. 1; 10 = MAXNGRAMSUGS n-gram suggestions).

🫶 ONLYMAXDIFF

• ONLYMAXDIFF — Remove all bad n-gram suggestions (default mode keeps one, see MAXDIFF).

💀 NOSPLITSUGS

• NOSPLITSUGS — Disable word suggestions with spaces.

⭐ SUGSWITHDOTS

• SUGSWITHDOTS — Add dot(s) to suggestions, if input word terminates in dot(s). (Not for LibreOffice dictionaries, because LibreOffice has an automatic dot expansion mechanism.)

---

🎀 REP

• REP number_of_replacement_definitions
• REP what replacement — This table specifies modifications to try first. The first REP line is the header of the table, followed by one or more REP data lines. With this table, Hunspell can suggest correct forms for typical spelling mistakes where the incorrect form differs by more than one letter from the correct form (see also "ph:"). The search string supports the regex boundary anchors (^ and $). For example, a possible English replacement table definition to handle misspelled consonants:

REP 5
REP f ph
REP ph f
REP tion$ shun
REP ^cooccurr co-occurr
REP ^alot$ a_lot

Note I: It's very useful to define replacements for the most typical one-character mistakes, too: with REP you can add higher priority to a subset of the TRY suggestions (suggestion list begins with the REP suggestions).

Note II: To suggest separated words, specify spaces as underscores:

REP 1
REP onetwothree one_two_three

Note III: The replacement table can be used for stricter compound word checking with the CHECKCOMPOUNDREP option.

---

🌈 MAP

• MAP number_of_map_definitions
• MAP string_of_related_chars_or_parenthesized_character_sequences — We can define language-dependent information on characters and character sequences that should be considered related (i.e. nearer than other chars not in the set) in the affix file (.aff) by a map table. With this table, Hunspell can suggest the right forms for words, which incorrectly choose the wrong letter or letter groups from a related set more than once in a word (see REP).

For example, a possible mapping could be for the German umlauted ü versus the regular u; the word Frühstück really should be written with umlauted u's and not regular ones.

MAP 1
MAP uü

Use parenthesized groups for character sequences (eg. for composed Unicode characters):

MAP 3
MAP ß(ss)  (character sequence)
MAP fi(fi)  ("fi" compatibility characters for Unicode fi ligature)
MAP (ó)o   (composed Unicode character: ó with bottom dot)

---

🧚 PHONE

• PHONE number_of_phone_definitions
• PHONE what replacement — PHONE uses a table-driven phonetic transcription algorithm borrowed from Aspell. It is useful for languages whose orthography is not pronunciation-based. You can add a full alphabet conversion and other rules for converting special letter sequences. For detailed documentation see http://aspell.net/man-html/Phonetic-Code.html.

Note: Multibyte UTF-8 characters do not yet work with bracket expressions. Dash range expressions still operate on single bytes, not UTF-8 characters. 😭

---

🍓 WARN

• WARN flag — This flag is for rare words, which are also often spelling mistakes, see option -r of command line Hunspell and FORBIDWARN.

🔥 FORBIDWARN

• FORBIDWARN — Words with flag WARN aren't accepted by the spell checker using this parameter.

💖 OPTIONS FOR COMPOUNDING 💖

Okay bestie, this is the compounding section and it's a lot, but we're gonna get through it together. Grab a snack. 🍓

• BREAK number_of_break_definitions
• BREAK character_or_character_sequence — this is where you set up brand new break points so Hunspell can split a word up and check the pieces separately. Use ^ to nuke characters at the start of the word and $ to nuke them at the end. Why would you want this? Because it's lowkey iconic for compounding with joining characters or strings — think the hyphen in English and German, or the hyphen and the n-dash in Hungarian. Dashes are honestly bad break points for tokenization a lot of the time, because compounds with dashes can also have parts that are just straight up invalid. With BREAK, Hunspell can check both sides of those compounds, splitting the words at dashes and n-dashes:

BREAK 2
BREAK -
BREAK --    # n-dash

Breaks are recursive, so foo-bar, bar-foo and foo-foo--bar-bar would all count as valid compounds. Slay. 🦋

Note: the default word break of Hunspell is exactly equivalent to this BREAK definition:

BREAK 3
BREAK -
BREAK ^-
BREAK -$

With that BREAK definition, Hunspell does not accept the -word and word- forms. But with this one:

BREAK 1
BREAK -

Switching off the default values entirely, like so:

BREAK 0

Note II: COMPOUNDRULE is actually the better move for handling dashes and other compound joining characters or strings. Reach for BREAK when you wanna check words with dashes or other joining characters and you have neither the time nor the ability to describe precise compound rules with COMPOUNDRULE (heads up: COMPOUNDRULE only handles the suffixation of the last word part of a compound word).

Note III: for command-line spell checking of words with extra characters, set the WORDCHARS parameter: WORDCHARS --- (go peek at the tests/break.* example).

• COMPOUNDRULE number_of_compound_definitions
• COMPOUNDRULE compound_pattern — define your own custom compound patterns with a regex-like syntax. The first COMPOUNDRULE line is a header holding the number of COMPOUNDRULE definitions that follow. Compound patterns are made of compound flags, parentheses, and the meta-characters * or ?. A flag followed by * matches a word sequence of 0 or more words flagged with that compound flag. A flag followed by ? matches 0 or 1 words flagged with that compound flag. Go look at the tests/compound*.* examples. 👑

Note: the en_US dictionary of OpenOffice.org uses COMPOUNDRULE for ordinal number recognition (1st, 2nd, 11th, 12th, 22nd, 112th, 1000122nd, etc.).

Note II: with long and numerical flag types, use only parenthesized flags: (1500)*(2000)?

Note III: COMPOUNDRULE flags work completely independently of the compounding mechanisms using COMPOUNDFLAG, COMPOUNDBEGIN, etc. (so use these flags on different word entries.)

• COMPOUNDMIN num — minimum length of words used for compounding. Default value is 3 letters.
• MAXCPDSUGS num — Max Compound Suggestions. Use 0 to disable suggesting from compounds. Default value is unlimited.
• COMPOUNDFLAG flag — words flagged with COMPOUNDFLAG may appear in compound words (except when the word is shorter than COMPOUNDMIN). Affixes with COMPOUNDFLAG also permit compounding of affixed words.
• COMPOUNDBEGIN flag — words flagged with COMPOUNDBEGIN (or with a flagged affix) may be first elements in compound words.
• COMPOUNDEND flag — words flagged with COMPOUNDEND (or with a flagged affix) may be last elements in compound words.
• COMPOUNDMIDDLE flag — words flagged with COMPOUNDMIDDLE (or with a flagged affix) may be middle elements in compound words.
• ONLYINCOMPOUND flag — a PFX or SFX affix flagged with ONLYINCOMPOUND may only appear inside compounds (Fuge-elements in German, fogemorphemes in Swedish). The ONLYINCOMPOUND flag also works on words (check tests/onlyincompound.*). Note: it's also super useful to flag compounding parts that aren't correct as a word on their own.
• COMPOUNDPERMITFLAG flag — prefixes are allowed at the beginning of compounds and suffixes are allowed at the end of compounds by default. Affixes with COMPOUNDPERMITFLAG may be inside of compounds.
• COMPOUNDFORBIDFLAG flag — suffixes with this flag forbid compounding of the affixed word. Dictionary words with this flag get removed from the beginning and middle of compound words, which overrides the effect of COMPOUNDPERMITFLAG.
• COMPOUNDMORESUFFIXES — allow twofold suffixes within compounds.
• COMPOUNDROOT flag — the COMPOUNDROOT flag marks compound words in the dictionary. A dictionary word with this flag counts as two words against the COMPOUNDWORDMAX limit. Hungarian uses this flag so that a compound built from an already compound stem reaches the word limit sooner.
• COMPOUNDWORDMAX number — set maximum word count in a compound word. (Default is unlimited.)
• CHECKCOMPOUNDDUP — forbid word duplication in compounds (e.g. foofoo). 🚫
• CHECKCOMPOUNDREP — forbid compounding if the (usually bad) compound word could be a non-compound word with a REP fault. Useful for languages with compound friendly orthography.
• CHECKCOMPOUNDCASE — forbid upper case characters at word boundaries in compounds.
• CHECKCOMPOUNDTRIPLE — forbid compounding if a compound word contains triple repeating letters (e.g. foo|ox or xo|oof). Bug: missing multi-byte character support in UTF-8 encoding (works only for 7-bit ASCII characters). 💀
• SIMPLIFIEDTRIPLE — allow simplified 2-letter forms of the compounds forbidden by CHECKCOMPOUNDTRIPLE. It's useful for Swedish and Norwegian (and for the old German orthography: Schiff|fahrt -> Schiffahrt).
• CHECKCOMPOUNDPATTERN number_of_checkcompoundpattern_definitions
• CHECKCOMPOUNDPATTERN endchars[/flag] beginchars[/flag] [replacement] — forbid compounding if the first word in the compound ends with endchars and the next word begins with beginchars and (optionally) they have the requested flags. The optional replacement parameter allows a simplified compound form.

The special endchars pattern 0 (zero) limits the rule to the unmodified stems (stems and stems with zero affixes):

CHECKCOMPOUNDPATTERN 0/x /y

Note: COMPOUNDMIN doesn't work correctly with the compound word alternation, so you may need to set COMPOUNDMIN to a lower value.

• FORCEUCASE flag — if the last word part of a compound has the FORCEUCASE flag, it forces capitalization of the whole compound word. E.g. the Dutch word straat (street) with the FORCEUCASE flag will be allowed only in capitalized compound forms, according to the Dutch spelling rules for proper names.
• COMPOUNDSYLLABLE max_syllable vowels — needed for special compounding rules in Hungarian. The first parameter is the maximum syllable count permitted in a compound when the number of words in the compound exceeds COMPOUNDWORDMAX. The second parameter is the list of vowels (used for counting syllables).
• SYLLABLENUM flags — needed for special compounding rules in Hungarian.

---

✨ AFFIX FILE OPTIONS FOR AFFIX CREATION ✨

• PFX flag cross_product number
• PFX flag stripping prefix [condition [morphological_fields...]]
• SFX flag cross_product number
• SFX flag stripping suffix [condition [morphological_fields...]] — okay so an affix is either a prefix or a suffix that gets attached to root words to form other words. Affix classes can be defined with literally any number of affix rules, and each class is identified by affix flags. The first line of an affix class definition is the header. Here are the fields of that header, bestie:
  • (0) Option name (PFX or SFX)
  • (1) Flag (the name of the affix class)
  • (2) Cross product (permission to combine prefixes and suffixes). Possible values: Y (yes) or N (no)
  • (3) Line count of the following rules.

And these are the fields of an affix rule:

• (0) Option name
• (1) Flag
• (2) stripping characters from the beginning (at prefix rules) or the end (at suffix rules) of the word
• (3) affix (optionally with flags of continuation classes, separated by a slash)
• (4) condition.
• (5) Optional morphological fields separated by spaces or tabs.

Zero stripping or affix is indicated by zero. A zero condition is indicated by a dot. The condition is a simplified, regular-expression-like pattern that must be met before the affix can be applied. (A dot matches an arbitrary character. Characters in brackets match any character from the bracketed subset. A dash has no special meaning, but a circumflex (^) immediately after the opening bracket inverts the character set.) 🧚

🌈 AFFIX FILE OTHER OPTIONS 🌈

okay bestie, this is the ✨everything else✨ pile of declarations — still iconic, still load-bearing, don't skip 👑

• CIRCUMFIX flag — an affix that's flagged with CIRCUMFIX can only be applied to a word when that word also has a prefix with CIRCUMFIX, and the other way around too (peep the circumfix.* test files in the source distribution). it's giving matching-set energy 💫
• FORBIDDENWORD flag — this flag marks a word form as forbidden. and because affixed forms get forbidden too, you can literally subtract a whole subset from the set of accepted affixed and compound words. Note: super useful for forbidding erroneous words generated by the compounding mechanism 🚫
• FULLSTRIP — with FULLSTRIP, affix rules can strip the full word, not just all but one character, before adding the affixes (see the fullstrip.* test files in the source distribution). Note: even without FULLSTRIP, conditions may match the full word length ✂️
• KEEPCASE flag — forbid uppercased and capitalized forms of words flagged with KEEPCASE. useful for special orthographies (measurements and currency often keep their case even in uppercased texts) and writing systems (e.g. keeping the lower case of IPA characters). also useful for words that would otherwise be erroneously written in the wrong case 🔒

Note: with a CHECKSHARPS declaration, words with sharp s and the KEEPCASE flag may be capitalized and uppercased, but uppercased forms of these words may not contain sharp s — only SS. see the germancompounding example in the tests directory of the Hunspell distribution.

• ICONV number_of_ICONV_definitions
• ICONV pattern pattern2 — define the input conversion table. use the underscore '_' to represent the last character of the string. for e.g. if you need to change <200D> to <FFF0> only if it appears at the end of the word, then…

ICONV <200D>_ <FFF0>

Note: useful to convert one type of quote to another one, or change a ligature 🔄

• OCONV number_of_OCONV_definitions
• OCONV pattern pattern2 — define the output conversion table 💅
• LEMMA_PRESENT flag — Deprecated. use the "st:" field instead of LEMMA_PRESENT 💀
• NEEDAFFIX flag — this flag marks virtual stems in the dictionary: words that are only valid when affixed (except when the dictionary word has a homonym or a zero affix). NEEDAFFIX also works with prefixes and prefix + suffix combinations (see tests/needaffix5.*) 🫶
• PSEUDOROOT flag — Deprecated. (former name of the NEEDAFFIX option.) 😭
• SUBSTANDARD flag — the SUBSTANDARD flag marks affix rules and dictionary words (allomorphs) that are not used in morphological generation, plus root words to be removed from suggestions. see also NOSUGGEST ✨
• WORDCHARS characters — WORDCHARS extends the tokenizer of the Hunspell command-line interface with additional word characters. for example, the dot, dash, n-dash, digits, and percent sign are word characters in Hungarian 🇭🇺
• CHECKSHARPS — the SS letter pair in uppercased (German) words may be sharp s (ß), or capital sharp s (ẞ, U+1E9E), which German orthography has permitted in uppercased words since 2017. Hunspell can handle this special casing with the CHECKSHARPS declaration (see also the KEEPCASE flag and tests/germancompounding example) in both spelling and suggestion 🎀

---

🦋 Morphological analysis 🦋

so Hunspell's dictionary items and affix rules may have optional space-or-tabulator-separated morphological description fields, and each one starts with a 3-character field ID (two letters and a colon, bestie, two letters and a colon) 👑

word/flags po:noun is:nom

Example: we define a simple resource with morphological informations, a derivative suffix (ds:) and a part of speech category (po:):

Affix file:

SFX X Y 1
SFX X 0 able . ds:able

Dictionary file:

drink/X po:verb

Test file:

drink
drinkable

Test:

$ analyze test.aff test.dic test.txt
> drink
analyze(drink) = po:verb
stem(drink) = po:verb
> drinkable
analyze(drinkable) = po:verb ds:able
stem(drinkable) = drinkable

you can see in the example that the analyzer concatenates the morphological fields in item and arrangement style 🌸

---

🌟 Optional data fields 🌟

default morphological and other IDs (used in suggestion, stemming and morphological generation):

• ph: — alternative transliteration for better suggestions, i.e. for misspellings related to the special orthography and pronunciation of the word. this is the best way to handle common misspellings, so it is worth adding a ph: field to the most affected few thousand dictionary words (or word pairs etc.) to get correct suggestions for their misspellings. for example:

Wednesday ph:wendsay ph:wensday
Marseille ph:maarsayl

Hunspell adds all ph: transliterations to the inner REP table, so it will always suggest the correct word for the specified misspellings with the highest priority 💖

the previous example is equivalent to the following REP definition:

REP 6
REP wendsay Wednesday
REP Wendsay Wednesday
REP wensday Wednesday
REP Wensday Wednesday
REP maarsayl Marseille
REP Maarsayl Marseille

the asterisk at the end of the ph: pattern means stripping the terminating character both from the pattern and the word in the associated REP rule:

pretty ph:prity*

will result

REP 1
REP prit prett

REP rule, resulting in the following correct suggestions:

*prity -> pretty
*pritier -> prettier
*pritiest -> prettiest

moreover, ph: fields can handle suggestions with more than two words, also different suggestions for the same misspelling:

do not know ph:dunno
don't know ph:dunno

results

*dunno -> do not know, don't know

Note: if available, ph: is used in n-gram similarity, too 👀

the ASCII arrow "->" in a ph: pattern means a REP rule (see REP), creating an arbitrary replacement rule associated with the dictionary item:

happy/B ph:hepy ph:hepi->happi

results

*hepy -> happy
*hepiest -> happiest

• st: — Stem. Optional: the default stem is the dictionary item in morphological analysis. the stem field is useful for virtual stems (dictionary words with the NEEDAFFIX flag) and for morphological exceptions, in place of new single-use morphological rules.

feet  st:foot  is:plural
mice  st:mouse is:plural
teeth st:tooth is:plural

word forms with multiple stems need multiple dictionary items:

lay po:verb st:lie is:past_2
lay po:verb is:present
lay po:noun

• al: — Allomorph(s). a dictionary item is the stem of its allomorphs. morphological generation needs stem, allomorph and affix fields.

sing al:sang al:sung
sang st:sing
sung st:sing

• po: — Part of speech category 🏷️
• ds: — Derivational suffix(es). stemming doesn't remove derivational suffixes. morphological generation depends on the order of the suffix fields.

in affix rules:

SFX Y Y 1
SFX Y 0 ly . ds:ly_adj

in the dictionary:

ably st:able ds:ly_adj
able al:ably

• is: — Inflectional suffix(es). all inflectional suffixes are removed by stemming. morphological generation depends on the order of the suffix fields.

feet st:foot is:plural

• ts: — Terminal suffix(es). terminal suffix fields are inflectional suffix fields "removed" by additional (not terminal) suffixes. useful for zero morphemes and affixes removed by splitting rules.

work/D ts:present

SFX D Y 2
SFX D   0 ed . is:past_1
SFX D   0 ed . is:past_2

typical example of the terminal suffix is the zero morpheme of the nominative case ✨

• sp: — Surface prefix. temporary solution for adding prefixes to the stems and generated word forms. see tests/morph.* example.
• pa: — Parts of the compound words. output fields of morphological analysis for stemming.
• dp: — Planned: derivational prefix.
• ip: — Planned: inflectional prefix.
• tp: — Planned: terminal prefix.

---

💅 Twofold suffix stripping 💅

Ispell's original algorithm strips only one suffix. Hunspell can strip an additional one (or an extra prefix in COMPLEXPREFIXES mode) 🔥

twofold suffix stripping is a significant improvement in handling the immense number of suffixes that characterize agglutinative languages, fr fr.

a second s suffix (affix class Y) will be the continuation class of the suffix able in the following example:

SFX Y Y 1
SFX Y 0 s .

SFX X Y 1
SFX X 0 able/Y .

Dictionary file:

drink/X

Test file:

drink
drinkable
drinkables

Test:

$ hunspell -m -d test <test.txt
drink st:drink
drinkable st:drink fl:X
drinkables st:drink fl:X fl:Y

in theory, twofold suffix stripping requires only the square root of the number of suffix rules compared with a one-level Hunspell implementation. in practice, this is what made it possible to elaborate the Hungarian inflectional morphology with twofold suffix stripping 👑

---

⭐ Extended affix classes ⭐

Hunspell can handle more than 65000 affix classes. there are three new syntaxes for specifying flags in affix and dictionary files 👛

FLAG long command sets 2-character flags:

FLAG long
SFX Y1 Y 1
SFX Y1 0 s 1

dictionary record with the Y1, Z3, F? flags:

foo/Y1Z3F?

FLAG num command sets numerical flags separated by comma:

FLAG num
SFX 65000 Y 1
SFX 65000 0 s 1

dictionary example:

foo/65000,12,2756

the third one is the Unicode character flags 🌈

---

🫶 Homonyms 🫶

Hunspell's dictionary can contain repeating elements that are homonyms:

work/A    po:verb
work/B    po:noun

an affix file:

SFX A Y 1
SFX A 0 s . sf:sg3

SFX B Y 1
SFX B 0 s . is:plur

Test file:

works

Test:

$ hunspell -d test -m <testwords
work st:work po:verb is:sg3
work st:work po:noun is:plur

this feature also gives a way to forbid illegal prefix/suffix combinations 😌

🔗 Prefix--suffix dependencies

okay so here's the tea about multi-step stripping — it has this absolutely iconic side effect: circumfixes just… work now? for free? no extra code, no drama. 💅

lemme explain. in Hungarian, superlatives are made by slapping leg- on the front AND -bb on the back of the adjective base at the same time. and the problem with the one-level architecture is there's literally no way to make the lexical licensing of particular prefixes and suffixes depend on each other, so wrong forms get recognized as valid — like *legvén = leg + vén old. not it. 🙈 before clusters showed up, the earlier HunSpell code had to hardwire a special treatment for the superlative. maybe that was fine for one single case, but bestie, prefix--suffix dependencies are everywhere in category-changing derivational patterns (cf. English payable, non-payable but *non-pay, or drinkable, undrinkable but *undrink). in simple words: here, the prefix un- is only legit if the base drink is suffixed with -able. if both these patters are handled by on-line affix rules and affix rules are checked against the base only, there's no way to express this dependency, and the system will necessarily over- or undergenerate. no cap. 😭

in the next example, suffix class R has a prefix continuation class (class P).

PFX P Y 1
PFX P   0 un . [prefix_un]+

SFX S Y 1
SFX S   0 s . +PL

SFX Q Y 1
SFX Q   0 s . +3SGV

SFX R Y 1
SFX R   0 able/PS . +DER_V_ADJ_ABLE

Dictionary:

2
drink/RQ  [verb]
drink/S   [noun]

Morphological analysis:

> drink
drink[verb]
drink[noun]
> drinks
drink[verb]+3SGV
drink[noun]+PL
> drinkable
drink[verb]+DER_V_ADJ_ABLE
> drinkables
drink[verb]+DER_V_ADJ_ABLE+PL
> undrinkable
[prefix_un]+drink[verb]+DER_V_ADJ_ABLE
> undrinkables
[prefix_un]+drink[verb]+DER_V_ADJ_ABLE+PL
> undrink
Unknown word.
> undrinks
Unknown word.

---

🌸 Circumfix

conditional affixes implemented by a continuation class are not enough for circumfixes, bestie, because a circumfix is one affix in morphology. so we also need the CIRCUMFIX option for correct morphological analysis. periodt. ✨

# circumfixes: ~ obligate prefix/suffix combinations
# superlative in Hungarian: leg- (prefix) AND -bb (suffix)
# nagy, nagyobb, legnagyobb, legeslegnagyobb
# (great, greater, greatest, most greatest)

CIRCUMFIX X

PFX A Y 1
PFX A 0 leg/X .

PFX B Y 1
PFX B 0 legesleg/X .

SFX C Y 3
SFX C 0 obb . +COMPARATIVE
SFX C 0 obb/AX . +SUPERLATIVE
SFX C 0 obb/BX . +SUPERSUPERLATIVE

Dictionary:

1
nagy/C    [MN]

Analysis:

> nagy
nagy[MN]
> nagyobb
nagy[MN]+COMPARATIVE
> legnagyobb
nagy[MN]+SUPERLATIVE
> legeslegnagyobb
nagy[MN]+SUPERSUPERLATIVE

---

🧩 Compounds

letting compounding run free yields a decrease in the precision of recognition, not to mention stemming and morphological analysis. 😬 although Ispell introduces lexical switches to license the compounding of bases, this proves not to be restrictive enough. for example:

# affix file
COMPOUNDFLAG X

2
foo/X
bar/X

with this resource, foobar and barfoo also are accepted words. wild.

this has been improved upon with the introduction of direction-sensitive compounding, i.e., lexical features can specify separately whether a base can occur as leftmost or rightmost constituent in compounds. this, however, is still insufficient to handle the intricate patterns of compounding, not to mention idiosyncratic (and language specific) norms of hyphenation. 😮‍💨

the Hunspell algorithm currently allows any affixed form of words that are lexically marked as potential members of compounds. Hunspell improved on this, and its recursive compound-checking rules make it possible to implement the intricate spelling conventions of Hungarian compounds. for example, the COMPOUNDWORDMAX, COMPOUNDSYLLABLE, COMPOUNDROOT, and SYLLABLENUM options can be used to encode the noteworthy Hungarian 6-3 rule. as a further example, in Hungarian derivative suffixes often modify compounding properties. Hunspell allows compounding flags on affixes, and provides two special flags (COMPOUNDPERMITFLAG and COMPOUNDFORBIDFLAG) to permit or prohibit compounding of the derived forms. 🫶

several Hunspell features are needed to handle German compounding:

# German compounding

# set language to handle special casing of German sharp s

LANG de_DE

# compound flags

COMPOUNDBEGIN U
COMPOUNDMIDDLE V
COMPOUNDEND W

# Prefixes are allowed at the beginning of compounds,
# suffixes are allowed at the end of compounds by default:
# (prefix)?(root)+(affix)?
# Affixes with COMPOUNDPERMITFLAG may be inside of compounds.
COMPOUNDPERMITFLAG P

# for German fogemorphemes (Fuge-element)
# Hint: ONLYINCOMPOUND is not required everywhere, but the
# checking will be a little faster with it.

ONLYINCOMPOUND X

# forbid uppercase characters at compound word bounds
CHECKCOMPOUNDCASE

# for handling Fuge-elements with dashes (Arbeits-)
# dash will be a special word

COMPOUNDMIN 1
WORDCHARS -

# compound settings and fogemorpheme for `Arbeit'

SFX A Y 3
SFX A 0 s/UPX .
SFX A 0 s/VPDX .
SFX A 0 0/WXD .

SFX B Y 2
SFX B 0 0/UPX .
SFX B 0 0/VWXDP .

# a suffix for `Computer'

SFX C Y 1
SFX C 0 n/WD .

# for forbid exceptions (*Arbeitsnehmer)

FORBIDDENWORD Z

# dash prefix for compounds with dash (Arbeits-Computer)

PFX - Y 1
PFX - 0 -/P .

# decapitalizing prefix
# circumfix for positioning in compounds

PFX D Y 29
PFX D A a/PX A
PFX D Ä ä/PX Ä
 .
 .
PFX D Y y/PX Y
PFX D Z z/PX Z

example dictionary:

4
Arbeit/A-
Computer/BC-
-/W
Arbeitsnehmer/Z

accepted compound words with the previous resource:

Computer
Computern
Arbeit
Arbeits-
Computerarbeit
Computerarbeits-
Arbeitscomputer
Arbeitscomputern
Computerarbeitscomputer
Computerarbeitscomputern
Arbeitscomputerarbeit
Computerarbeits-Computer
Computerarbeits-Computern

not accepted compounds:

computer
arbeit
Arbeits
arbeits
ComputerArbeit
ComputerArbeits
Arbeitcomputer
ArbeitsComputer
Computerarbeitcomputer
ComputerArbeitcomputer
ComputerArbeitscomputer
Arbeitscomputerarbeits
Computerarbeits-computer
Arbeitsnehmer

this solution is still not ideal, however, and will be replaced by a pattern-based compound-checking algorithm which is closely integrated with input buffer tokenization. patterns describing compounds come as a separate input resource that can refer to high-level properties of constituent parts (e.g. the number of syllables, affix flags, and containment of hyphens). the patterns are matched against potential segmentations of compounds to assess wellformedness. 💀

---

🌈 Unicode character encoding

both Ispell and Myspell use 8-bit character encodings, which is a major deficiency when it comes to scalability. 😭 although a language like Hungarian has a standard 8-bit character set (ISO 8859-2), that set does not allow a full implementation of Hungarian orthographic conventions. for instance, the '--' symbol (n-dash) is missing from this character set, despite being not only the official symbol for delimiting parenthetic clauses in the language but also occurring in compound words as a special big hyphen.

MySpell has some 8-bit encoding tables, but there are also languages without a standard 8-bit encoding. for example, a lot of African languages have non-Latin or extended-Latin characters.

similarly, using the original spelling of certain foreign names like Ångström or Molière is encouraged by the Hungarian spelling norm, and, since characters 'Å' and 'è' are not part of ISO 8859-2, when they combine with inflections containing characters only in ISO 8859-2 (like elative -ből, allative -től or delative -ről with double acute), these result in words (like Ångströmről or Molière-től.) that can not be encoded using any single ASCII encoding scheme. 🤯

the problems raised by 8-bit encodings have long been recognized by proponents of Unicode. it is clear that trading efficiency for encoding-independence has its advantages when it comes to a truly multilingual application. Hunspell implements memory- and time-efficient Unicode handling. with non-UTF-8 character encodings, Hunspell works with the original 8-bit strings. with UTF-8, affixes and words are stored in UTF-8 and handled mostly in UTF-8 during analysis; for condition checking and suggestion they are converted to UTF-16. Unicode text analysis and spell checking have a minimal (0-20%) time overhead, and a minimal or reasonable memory overhead that depends on the language (its UTF-8 encoding and affixation). slay. ✨

---

🎀 Conversion of aspell dictionaries

aspell dictionaries can be easily converted to Hunspell format. conversion steps:

dictionary (xx.cwl -> xx.wl):

preunzip xx.cwl
wc -l < xx.wl > xx.dic
cat xx.wl >> xx.dic

affix file

if the affix file exists, copy it:

cp xx_affix.dat xx.aff

if not, create it with the suitable character encoding (see xx.dat)

echo "SET ISO8859-x" > xx.aff

or

echo "SET UTF-8" > xx.aff

it is useful to add a TRY option listing the characters of the dictionary in order of frequency, to drive edit-distance suggestions:

echo "TRY qwertzuiopasdfghjklyxcvbnmQWERTZUIOPASDFGHJKLYXCVBNM" >>xx.aff

---

👀 SEE ALSO

• hunspell (1), ispell (1), ispell (4)

---

okay bestie that's the whole page, we made it, you're officially a hunspell scholar now 👑💖 this iconic lil manual page is hunspell(5) and it's dated 2026-04-30 — go forth and spell things correctly, i'm so proud of you fr fr 🦋🌸