文書Documentation

Configuration

Kotoshu configuration: resolution order, KOTOSHU_* environment variables, XDG paths, dictionary types, and the personal dictionary.

One resolver, four sources, a fixed order — Kotoshu configuration is predictable by construction.

設定Settings

Resolution order

Every option resolves through the same chain, highest first. A CLI flag beats an environment variable, which beats a programmatic value, which beats the default.

CLI flags  →  ENV (KOTOSHU_*)  →  programmatic  →  defaults
highest                                            lowest

The programmatic layer is the global singleton reached through Kotoshu.configure:

Kotoshu.configure do |config|
config.default_language = "en"
config.max_suggestions = 5
config.dictionary_type = :hunspell
config.dictionary_path = "/usr/share/hunspell/en_US.dic"
end

After changing configuration, call Kotoshu.reset_spellchecker so the next check rebuilds with the new values.

Environment variables

Any variable below feeds the same resolver, so it applies to both the CLI and the library. The commonly used set:

Variable	Purpose	Default
`KOTOSHU_CACHE_PATH`	Cache directory — dictionaries, frequency lists, models	~/.cache/kotoshu
`KOTOSHU_CONFIG_PATH`	User config directory	~/.config/kotoshu
`KOTOSHU_DATA_PATH`	Data directory — audit log	~/.local/share/kotoshu
`KOTOSHU_OFFLINE`	Never download; use cached resources only	unset (off)
`KOTOSHU_NO_ONNX`	Disable the semantic path even when onnxruntime is installed	unset
`KOTOSHU_LANGUAGE`	Configured language	en-US
`KOTOSHU_DEFAULT_LANGUAGE`	Fallback when detection is inconclusive	en
`KOTOSHU_MAX_SUGGESTIONS`	Suggestions returned per word	10
`KOTOSHU_DICTIONARY_TYPE`	Dictionary backend	unix_words
`KOTOSHU_PERSONAL_DIC`	Personal dictionary file	config dir + personal.dic

XDG paths

Kotoshu follows the XDG Base Directory specification. A KOTOSHU_*_PATH variable wins over the generic XDG_*_HOME, which wins over the default below.

Concern	Default path	Overridden by
Dictionaries, frequency lists, ONNX models	`~/.cache/kotoshu/`	KOTOSHU_CACHE_PATH, XDG_CACHE_HOME
Personal dictionary, kotoshu.cfg	`~/.config/kotoshu/`	KOTOSHU_CONFIG_PATH, XDG_CONFIG_HOME
Audit log	`~/.local/share/kotoshu/audit.log`	KOTOSHU_DATA_PATH, XDG_DATA_HOME

Dictionary types

dictionary_type selects the backend the dictionary is loaded from:

Type	Use it when
`:unix_words`	Default. A flat system word list such as /usr/share/dict/words; Kotoshu detects the file when one exists
`:plain_text`	Your own one-word-per-line list; requires dictionary_path
`:custom`	Words supplied in code via custom_words — tests and small embedded lists
`:hunspell`	An .aff/.dic pair with affix rules and compounding — the format kotoshu setup downloads; the .aff path is derived from the .dic path
`:cspell`	Reusing cspell-format dictionary files

Personal dictionary

Words you accept live in one personal dictionary, shared across languages, at ~/.config/kotoshu/personal.dic (or KOTOSHU_PERSONAL_DIC). The kotoshu personal subcommand manages it:

kotoshu personal add kotoshu
kotoshu personal import project-terms.txt   # one word per line
kotoshu personal list
kotoshu personal path

Where caches live and how they expire is covered in Caching.