Organization dictionary: Self-hosted management

This guide covers how to manage organization dictionaries through configuration files on self-hosted deployments, including Docker.

For an overview of organization dictionaries, key concepts, integration configuration, and limitations, refer to the Organization dictionary overview →.

Creating a dictionary

Step 1: Prepare the wordlist file

Create a new file in .txt format with UTF-8 encoding. Add one word per line. It's recommended to sort the wordlist in alphabetical order.

You must add an empty line at the end of the file. Without it, the last word in the list won't be recognized.

For word rules and validation details, refer to the Organization dictionary overview →.

Step 2: Place the file on the server

Place the wordlist file in the dictionary directory:

Windows/Linux installation

<WebSpellChecker_Installation_Path>/AppServer/CustomDictionaries/

Docker

/dictionaries/CustomDictionaries/

Mount /dictionaries to persistent storage so files survive container replacement and restarts.

Step 3: Register the dictionary in the configuration

Open the configuration file:

Windows/Linux installation

<WebSpellChecker_Installation_Path>/AppServer/CustDictConfig.xml

Docker

/dictionaries/CustomDictionaries/CustDictConfig.xml

Inside the <CustomerDb> tag, add a new <Dictionary> entry with the following values:

• DicId — a unique numeric ID (for example, "3"). Make sure this ID isn't already used by another dictionary in the file.

• FileName — the name of your .txt wordlist file.

• Description — the description for your dictionary. The description must be unique.

• LangShortName — the language shortcode (for example, en_US).

Example:

<CustomerDb>
    <Dictionary DicId="3">
        <FileName>medical_terms.txt</FileName>
        <Description>Medical terms</Description>
        <LangShortName>en_US</LangShortName>
    </Dictionary>
</CustomerDb>

You can add multiple <Dictionary> entries inside the same <CustomerDb> tag:

<CustomerDb>
    <Dictionary DicId="3">
        <FileName>medical_terms.txt</FileName>
        <Description>Medical terms</Description>
        <LangShortName>en_US</LangShortName>
    </Dictionary>
    <Dictionary DicId="4">
        <FileName>legal_terms_de.txt</FileName>
        <Description>Legal terms</Description>
        <LangShortName>de_DE</LangShortName>
    </Dictionary>
</CustomerDb>

Editing and deleting dictionaries

Editing a wordlist. Open the .txt file and modify the words directly. Save the file in UTF-8 encoding. Remember to keep an empty line at the end of the file.

Editing dictionary configuration. Update the DicId, FileName, or LangShortName values in CustDictConfig.xml as needed.

Deleting a dictionary. Remove the corresponding <Dictionary> entry from CustDictConfig.xml. You can also delete the .txt file from the CustomDictionaries directory.

Restart AppServer after any configuration changes for them to take effect.

Shared dictionaries across multiple servers

If you run multiple copies of the WProofreader application in a dynamic infrastructure where servers are added or removed based on workload, you should store dictionaries on a shared volume so all instances use the same wordlists.

How it works

Instead of keeping dictionary files on each server's local disk, you point all instances of the WProofreader application to a single shared storage location. This way, any changes to dictionaries are immediately available to all instances without manual synchronization.

Setting up shared storage

1. Create a shared volume accessible by all instances of the WProofreader application. The type of shared storage depends on your deployment:

   • Linux: a network file system (NFS) mount or similar shared volume

   • Windows: a shared network folder (SMB/CIFS)

   • Docker: a mounted volume with persistent storage (for example, Amazon EFS)

2. Move your dictionary files to the shared volume. This includes your wordlist .txt files and the CustDictConfig.xml configuration file.

3. Update the configuration on each instance. Open <WebSpellChecker_Installation_Path>/AppServer/AppServerX.xml and update the following paths to point to your shared volume:

<CustDictConfig>/path_to_shared-volume/CustDictConfig.xml</CustDictConfig>
<CustDictDir>/path_to_shared-volume/CustomDictionaries</CustDictDir>

1. Restart AppServer on each instance for the changes to take effect.

All instances will now read from and write to the same shared location. Any dictionaries you create or modify will be available across your entire infrastructure.

FAQ

Do I need to restart AppServer after making changes?

No. Changes to CustDictConfig.xml and wordlist files take effect without restarting AppServer.

Why isn't the last word in my dictionary being recognized?

The wordlist file must end with an empty line (a newline character after the last word). Without it, the last word won't be processed.

Can I use the same dictionary file for multiple languages?

No. Each dictionary entry in CustDictConfig.xml is tied to a specific language via LangShortName. If you need the same words for multiple languages, create separate dictionary entries with different language shortcodes.

How many dictionaries can I add?

AppServer supports up to 250 custom dictionaries by default. Adjust the limit with the CustDictsLimit parameter in AppServerX.xml.

How do I keep dictionaries in sync across multiple servers or containers?

Use a shared volume (NFS, SMB/CIFS, or a mounted persistent volume for Docker) and point all instances of the WProofreader application to it by updating the <CustDictConfig> and <CustDictDir> paths in AppServerX.xml. See the "Shared dictionaries across multiple servers" section above.

What file encoding should I use for the wordlist?

UTF-8. The wordlist must be a plain .txt file with one word per line.