Style guide: Self-hosted

This guide covers how to manage custom style guide rules for self-hosted WProofreader installations by working with CSV files directly. For an overview of the style guide feature, custom rules structure, case sensitivity, and limitations, refer to the Style guide overview →.

File structure

Custom style guide rules are stored as CSV files in the StyleGuide/client directory inside your WProofreader installation path:

<WProofreader_Installation_Path>/AppServer/StyleGuide/client/

Rules are organized by language. Each language has its own folder named after its language alias (as defined in your AppServerX.xml file). For example, en applies rules to all English dialects, while en_GB applies only to British English. Use common for rules that apply regardless of language.

Example folder structure:

StyleGuide/
└── client/
    ├── common/
    │   └── brandname_terminology.csv
    ├── en/
    │   └── myorg_writing_style.csv
    ├── en_GB/
    │   └── myorg_british_spelling.csv
    └── de/
        └── myorg_writing_style.csv

All changes inside StyleGuide/client are applied automatically without restarting the WProofreader application.

File naming

The CSV file name defines the namespace and category for the rules it contains. It consists of two parts separated by the first underscore (_):

• The text before the first underscore is the namespace (prefix) for all rules and categories in the file. This is typically your company or organization name.

• The text after the first underscore is the category name for the rule set. Categories are logical groupings of rules. The category name can contain additional underscores.

For example, the file myorg_writing_style.csv creates rules under the namespace myorg in the category writing_style.

Use descriptive file names that clearly indicate the purpose of the rules. Organize rules by scope (common vs. language-specific).

Multi-language categories

Custom rule categories can span multiple languages. Files with the same name in different language folders belong to the same category. For example:

StyleGuide/client/en/mycompany_example.csv
StyleGuide/client/de/mycompany_example.csv

These add rules to the same category in English and German respectively. Keep in mind that disabling a category applies to all languages it's defined for.

CSV file format

Each CSV file must have a header row with the following columns: Patterns, Suggestions, Description, Context include, and Context exclude.

Patterns,Suggestions,Description,Context include,Context exclude
WSC,WebSpellChecker,Use the full company name instead.,product,
marketing team,Marketing team,Use capitalization for official department names.,company;our,external

Rules follow these formatting conventions:

• If a rule has multiple patterns or suggestions, separate them with a semicolon (;).

• Context include and Context exclude values are also separated by semicolons.

• The Description, Context include, and Context exclude columns can be left empty.

• To disable a rule, add # before the first pattern value in the row.

File requirements

• CSV format only.

• The file must not exceed 5 MB.

• Maximum of 2,000 rules per file.

Creating custom rules

1. Navigate to the StyleGuide directory in your WProofreader installation path: <WProofreader_Installation_Path>/AppServer/StyleGuide

2. Inside the client folder, create a folder for the target language (e.g. en for English, de for German). Use the language alias from your AppServerX.xml file. If there are two aliases for a language, you can use either one. For language-independent rules, use the common folder.

3. Create a CSV file inside the language folder following the naming conventions and format described above.

For example, to create English-specific rules for your organization:

<WProofreader_Installation_Path>/AppServer/StyleGuide/client/en/myorg_writing_style.csv

The rules take effect automatically after the file is saved.

Editing and deleting rules

Open the CSV file in a text editor or spreadsheet application, make your changes, and save. Changes are picked up automatically.

To delete an entire rule set, remove the CSV file from the language folder.

To temporarily disable a single rule without removing it, add # before the pattern value in that row.

Limits and behavior

File size limit

• If a file exceeds 5 MB when the WProofreader application starts, it isn't loaded.

• If a file exceeds 5 MB at runtime (e.g. after editing), the rules in that file aren't updated internally. The previously loaded version of the rules continues to work. The file isn't reloaded until its size is back within the limit.

File count limit

• Maximum of 50 files per language folder.

• If there are more than 50 files in a language folder when the WProofreader application starts, none of the files in that folder are loaded.

• If files are added during runtime and the total exceeds 50, the new files aren't used until the count drops to 50 or fewer. Files that were already loaded continue to work, and edits to those files are still applied.

FAQ

Do I need to restart AppServer after changing rules?

No. All changes inside StyleGuide/client are applied automatically.

Can I use the same category across multiple languages?

Yes. Create files with the same name in different language folders (e.g. en/myorg_example.csv and de/myorg_example.csv). Disabling the category will disable it for all languages.

What happens if my CSV file has errors?

If the file can't be parsed (e.g. malformed CSV), the rules from that file won't be loaded. Check the file format and ensure it follows the column structure described above.