# 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 →](/features/custom-dictionary/organization-dictionary.md).

### 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 →](/features/custom-dictionary/organization-dictionary.md).

#### Step 2: Place the file on the server

Place the wordlist file in the dictionary directory:

{% tabs %}
{% tab title="Windows/Linux installation" %}

```
<WebSpellChecker_Installation_Path>/AppServer/CustomDictionaries/
```

{% endtab %}

{% tab title="Docker" %}

```
/dictionaries/CustomDictionaries/
```

Mount `/dictionaries` to persistent storage so files survive container replacement and restarts.
{% endtab %}
{% endtabs %}

#### Step 3: Register the dictionary in the configuration

Open the configuration file:

{% tabs %}
{% tab title="Windows/Linux installation" %}

```
<WebSpellChecker_Installation_Path>/AppServer/CustDictConfig.xml
```

{% endtab %}

{% tab title="Docker" %}

```
/dictionaries/CustomDictionaries/CustDictConfig.xml
```

{% endtab %}
{% endtabs %}

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.
* `LangShortName` — the language shortcode (for example, `en_US`).

Example:

```xml
<CustomerDb>
    <Dictionary DicId="3">
        <FileName>medical_terms.txt</FileName>
        <LangShortName>en_US</LangShortName>
    </Dictionary>
</CustomerDb>
```

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

```xml
<CustomerDb>
    <Dictionary DicId="3">
        <FileName>medical_terms.txt</FileName>
        <LangShortName>en_US</LangShortName>
    </Dictionary>
    <Dictionary DicId="4">
        <FileName>legal_terms_de.txt</FileName>
        <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:

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

4. **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?

Yes. Changes to `CustDictConfig.xml` or the wordlist files require an AppServer restart to take effect.

#### 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 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.


---

# 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/features/custom-dictionary/organization-dictionary-self-hosted-management.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.