Vocabularies (available since
v2.3) allow you to maintain custom lists of
terminology independent of your styles.
Vocab is a single folder (stored at
consisting of two plain-text files—
reject.txt—that contain one word, phrase, or regular expression per
The effects of using a custom
Vocab are as follows:
accept.txtare added to every exception list in all styles listed in
BasedOnStyles—meaning that you now only need to update your project's vocabulary to customize third-party styles (rather than the styles themselves).
conditional-based rules take the entries as-is (case-sensitive), while
spelling-based rules are always case-insensitive.
accept.txtare automatically added to a substitution rule (
Vale.Terms), ensuring that any occurrences of these words or phrases exactly match their corresponding entry in
reject.txtare automatically added to an existence rule (
Vale.Avoid) that will flag all occurrences as errors.
This means that your exceptions can be developed independent of a style, allowing you to use the same exceptions with multiple styles or switch styles without having to re-implement them.
Vocab entries are stored in
<StylesPath>/Vocab/<name>/ and are then
.vale.ini. For example, consider the following
/styles) contains two styles (
MyOtherStyle) and two vocabularies (
Marketing). You can then
simply reference these entries by their folder name:
reject.txt are plain-text files that take one
entry per line:
The entries are case-sensitive (except for rules extending
mentioned above) and may also be regular expressions.
Relation to ignore files
The functionality of vocabularies is similar to the existing concept of
ignore files. The major differences
are that vocabularies apply to multiple extension points (rather than just
spelling), support regular expressions, and have built-in rules associated
with them (
In general, this means that ignore files are for style creators while vocabularies are for style users:
If you're developing or maintaining a style, you may still want to include a custom
MyStyle.Spelling—that packages its own ignore files.
As a user of styles, vocabularies should be able to replace the use of ignore files completely.
For example, if you were using
<StylesPath>/vocab.txtfile prior to
v2.3, you can simply copy the contents of
<StylesPath>/Vocab/<MyVocab>/accept.txtand it'll work the same (you may also want to disable
Vale.Avoidto replicate the exact experience).