> For the complete documentation index, see [llms.txt](https://docs.wproofreader.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.wproofreader.com/v6.12.0/deployment/configuration/spell-check-engine/suggestion-prioritization-mechanism.md).

# Suggestion prioritization mechanism

The suggestion prioritization mechanism is designed to allow the admins of the WebSpellChecker on-premise version to influence and change the default behavior of how the corrections are generated and shown to end-users. Using this mechanism, the admins can create a list of rules which will be used during the process of generating corrections.

Here is a list of use cases where the suggestion prioritization mechanism will come in handy:

* Common spelling errors (e.g. “teh” –> “the”)
* Synonyms and alternatives

### Rules categories <a href="#draft-suggestionprioritizationmechanism-rulescategories" id="draft-suggestionprioritizationmechanism-rulescategories"></a>

There is a list of main categories that can be used to create your custom rules for the suggestion prioritization.

| Category name         | Description                                     |
| --------------------- | ----------------------------------------------- |
| ANY\_POSITION         | Any position in a word                          |
| WORD\_INITIAL         | The first letter in a word                      |
| FIRST\_OR\_SECOND     | The first or the second letter in a word        |
| MIDDLE\_OF\_THE\_WORD | Not the first and not the last letter in a word |
| END\_OF\_THE\_WORD    | The last letter in a word (end of a word)       |
| ENTIRE\_WORD          | The entire word                                 |

### Syntax and configuration File <a href="#draft-suggestionprioritizationmechanism-syntaxandconfigurationfile" id="draft-suggestionprioritizationmechanism-syntaxandconfigurationfile"></a>

All the rules should be written in a special **\*.ini** configuration file.

#### Configuration file <a href="#draft-suggestionprioritizationmechanism-configurationfile" id="draft-suggestionprioritizationmechanism-configurationfile"></a>

The configuration file for the suggestion prioritization mechanism must match the next requirements.

* File format: \*.ini
* Encoding: UTF-8
* Target location: \[WebSpellChecker\_Installation\_Folder]/AppServer/Resources/
* Example of the file name: “suggestions\_prioritization\_rules\_lang\_shortcode.ini”. Visit [Supported languages](/v6.12.0/features/supported-languages.md) to find out what languages are supported and what are their language codes.

You can have more than one configuration file with rules for different languages. Also, you can reuse a single file with rules for a list of languages that might have the same rules (e.g. English dialects).

#### Syntax <a href="#draft-suggestionprioritizationmechanism-syntax" id="draft-suggestionprioritizationmechanism-syntax"></a>

The syntax of the configuration file with rules for the suggestion prioritization must follow the next requirements.

* Rules blocks must start with the category name.
* Specific rule follows after the category name to which it belongs. You can have more than one rule under a single category.
* Each rule should be written on a new line.
* The rule consists of two values separated with an empty space: \[value 1] \[space] \[value 2]

```javascript
CATEGORY_NAME
[value 1] [space] [value 2]
[value 1] [space] [value 2]
...
CATEGORY_NAME
[value 1] [space] [value 2]
...
blank line
```

If you are using the ENTIRE\_WORD rule, make sure that all words that you use are present in the language or custom dictionaries.

This is an example of configuration file syntax with two rules:

* End of the word. We added two letters separated with a space: “z” and “s”. This rule will word for all misspelled words which end on “z”, and provide similar suggestions which end on “s”.
* Entire word. In this rule, we replace the entire word with the other separated with a space: “teh” and “the”. Thus, when the user types “teh”, the system will suggest correcting it to “the”.

```javascript
END_OF_THE_WORD
z s
ENTIRE_WORD
teh the
```

### Getting started <a href="#draft-suggestionprioritizationmechanism-gettingstarted" id="draft-suggestionprioritizationmechanism-gettingstarted"></a>

{% stepper %}
{% step %}

#### Create and place the rules file

Once a new configuration file with the rules is ready and placed in the \[WebSpellChecker\_Installation\_Folder]/AppServer/Resources/ folder, enable suggestion prioritization in the relevant **Language** block in **AppServerX.xml**.
{% endstep %}

{% step %}

#### Open AppServerX.xml

Go to the \[WebSpellChecker\_Installation\_Folder]/AppServer/ folder and open the **AppServerX.xml** file.
{% endstep %}

{% step %}

#### Find the target language block

Find the `<Language ...>` block for the language you want to configure (for example, `Id="en_US"`).
{% endstep %}

{% step %}

#### Configure `<SuggestionPrioritization>`

Add (or update) the `<SuggestionPrioritization ...>` section inside that `Language` block:

* **Enabled** – turns suggestion prioritization on/off for the language.
* **ConfigFile Path** – path to a rule file (relative to `.../AppServer/Resources/`).
* **ConfigFile AdvancedSearch** – enables advanced lookup for suggestions (uses not only the initial engine suggestions, but also language dictionaries, global custom dictionaries, and personal user dictionaries).

You can add more than one `ConfigFile` entry. This is useful when you want:

* one file with language-specific rules, plus
* one shared file with common rules reused across languages.

```javascript
<Language Id="en_US" Enabled="true">
	<!-- American English (United States) -->
	...
	<SuggestionPrioritization Enabled="true">
		<ConfigFile Path="en/en_US_suggestion_rules.ini" AdvancedSearch="true"/>
		<ConfigFile Path="common/common_suggestion_rules.ini" AdvancedSearch="true"/>
	</SuggestionPrioritization>
	...
</Language>
```

If you want to use suggestion prioritization for several languages, configure `<SuggestionPrioritization>` separately in each corresponding `<Language>` block.
{% endstep %}

{% step %}

#### Save and restart AppServer

Once all the changes are done, save the file.

Restart AppServer to apply changes in `AppServerX.xml`.

To restart: [stop](https://docs.wproofreader.com/v6.12.0/deployment/configuration/spell-check-engine/pages/IA2KNQLXDh85TwDivL4y#mainappservercommands-stopappserverwindowslinux2.stopappserver) the application, then [start](https://docs.wproofreader.com/v6.12.0/deployment/configuration/spell-check-engine/pages/IA2KNQLXDh85TwDivL4y#mainappservercommands-startappserverwindowslinux1.startappserver) it again.

Use [Main AppServer commands](/v6.12.0/deployment/configuration/application-server/main-appserver-commands.md).
{% endstep %}
{% endstepper %}