# 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 %}


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.wproofreader.com/v6.12.0/deployment/configuration/spell-check-engine/suggestion-prioritization-mechanism.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.