MXSpell
Java spellchecker library using Hunspell dictionaries. Requires Java 21+. No external dependencies.
Core Classes
SpellChecker
Main entry point for spellchecking operations.
Constructor:
SpellChecker(String language, String dictionaryFolder) throws IOException
language: BCP47 language code (e.g., "en-US", "de-DE", "fr"). Internally converted to match dictionary file names with underscores.
dictionaryFolder: Path to directory containing dictionaries
The constructor looks for dictionaries in two formats:
- Subdirectory named after the language containing
.aff and .dic files
- ZIP file named
{language}.zip containing the dictionary files
Methods:
String[] suggest(String word)
Returns spelling suggestions for a word. Empty array if word is correct.
Adds a word to the learned words list (persists across sessions).
Ignores a word for the current session only.
Map<String, String[]> checkString(String text)
Checks all words in a text string. Returns map of misspelled words to their suggestions.
Dictionary getDictionary()
Returns the underlying Dictionary object for advanced operations.
Dictionary
Manages word lookup and validation. Obtained via SpellChecker.getDictionary().
Key Methods:
DictionaryEntry lookup(String word)
Looks up a word in the dictionary. Returns null if not found.
List<String> getWords(DictionaryEntry entry) throws IOException
Returns all word forms generated from a dictionary entry by applying affix rules.
boolean isValidCompound(String word)
Checks if a word is valid as a compound word based on compound flags.
void learn(String word)
void ignore(String word)
Set<String> getLearnedWords()
Set<String> getIgnoredWords()
Manage learned and ignored words.
DictionaryEntry
Represents a word entry from the dictionary.
Constructor:
DictionaryEntry(String word, String flags, String morphology)
Methods:
String getWord()
String getFlags()
String getMorphology()
Basic Usage
import com.maxprograms.mxspell.SpellChecker;
// Initialize with US English dictionary
SpellChecker checker = new SpellChecker("en-US", "path/to/dictionaries");
// Check a word
String[] suggestions = checker.suggest("speling");
if (suggestions.length > 0) {
System.out.println("Did you mean: " + String.join(", ", suggestions));
}
// Check multiple words
Map<String, String[]> results = checker.checkString("The speling is rong");
for (Map.Entry<String, String[]> entry : results.entrySet()) {
System.out.println(entry.getKey() + " -> " + String.join(", ", entry.getValue()));
}
// Learn a word
checker.learn("customword");
// Ignore a word for this session
checker.ignore("propertyname");
Supported Features
- Affix rules (prefixes and suffixes)
- Cross-product affix application (prefix+suffix combinations)
- Compound word validation with full flag support
- Replacement tables (REP directive)
- TRY characters for suggestion generation
- FORBIDDENWORD flag (rejects forbidden words)
- NOSUGGEST flag (excludes words from suggestions)
- KEEPCASE flag (enforces exact case matching)
- Encoding detection (UTF-8, ASCII, ISO-8859-*, Windows codepages)
- Thread-safe operations
- Learned and ignored words
Dictionary Format
Requires Hunspell-compatible dictionaries:
.aff file: Affix rules and configuration
.dic file: Word list with flags
Dictionary structure:
dictionaryFolder/
language/
index.aff
index.dic
Or as ZIP files:
dictionaryFolder/
language.zip (containing .aff and .dic)
Building
Output: lib/mxspell.jar
Thread Safety
All classes are thread-safe. Dictionary and AffixParser use immutable collections after initialization. SpellChecker can be safely shared across threads.