OLD Style guide builder
The style guide functionality was introduced in v5.29.0. It is now available to all paid users. Users with a self-hosted product version can create and manage their company style guides, including custom categories and rules. Other paid users can currently create and manage custom style guide rules through an API or admin panel.
In addition, all users have access to a predefined set of rules built on top of the style guide functionality. These rules support inclusive, respectful, and authentic language checks across multiple languages.
Key features:
Custom rules: With the Style Guide functionality, all paid users can create and manage their own linguistic rules and patterns. This ensures smooth and precise communication tailored to specific business requirements.
Custom categories: Users with a self-hosted product version can create and organize custom categories, enabling more advanced structuring of their company style guide.
Style check (predefined rule lists): We provide predefined sets of rules to address non-inclusive, profane, and non-authentic writing. These comprehensive rule sets help maintain a professional and respectful tone across written content. Users can control how detected issues are displayed directly from the UI, in line with the Style Guide rules.
This new feature is available for WProofreader for RTEs, the plugin for CKEditor 5, Web API, and the browser extension.
1. How to configure Custom guide functionality?
Cloud users have their text verified against a predefined set of WebSpellChecker-provided rules, which can be enabled or disabled individually or as a group. In addition, all paid users can create and manage custom style guide rules, currently available via API or the admin panel.
Users with a self-hosted version have extended capabilities, including full control over their Style Guide setup, with the ability to create and organize both custom rules and categories.
1.1. Managing Custom guide functionality state for on-premises version 5.29.0.0+ via AppServerX.xml file (back-end)
Style Guide functionality is enabled by default. The found mistakes are highlighted with the yellow lines starting v.5.29.1.0. The folder with appropriate files for on-premises clients is located in the core AppServer directory:
<Installation_Path>\WebSpellChecker\AppServer\StyleGuide
Starting with WebSpellChecker standalone version 5.29.0.0 you can manage the state of the Style Guide functionality follow the steps below:
Locate and open the AppServerX.xml configuration file for editing. By default, the file is located in <Installation_Path>/AppServer/AppServerX.xml.
Before making any changes to the AppServerX.xml file, it is recommended to stop AppServer.
Find a block with the needed language by language name or its shortcode. For example, American English
4. Change the value for Enabled state from true to false.
5. Save the updated version of the AppServerX.xml file and start AppServer to apply changes.
If you run WebSpellChecker on Docker, you can create an updated image from a modified Docker container to use it further.
1.2. Managing rules statuses for standalone version 5.29.0.0+ via disabledRules.json file (back-end)
The WebSpellChecker on-premises clients with access to the internal software configuration can disable a particular Style Guide or grammar rule by using the ‘disabledRules.json’ configuration file, which is located by default in the root installation directory <Installation_Path>\WebSpellChecker\AppServer
This is a regular JSON file (with comments supported) with two array values: ‘categories’ and ‘rules’, for the lists of category and rule IDs, respectively.
As for the built-in ones, we have several categories of custom rules
English: WSC_GENDERED_AND_ABLEIST_LANGUAGE, WSC_RACE_AND_ETHNICITY_INSULTS, WSC_STRONG_SWEAR_LANGUAGE
German: WSC_FOREIGN_WORDS WSC_RACE_AND_ETHNICITY_INSULTS WSC_STRONG_SWEAR_LANGUAGE WSC_ANGLICISM_AND_ALTERNATIVE
Spanish: WSC_RACE_AND_ETHNICITY_INSULTS WSC_STRONG_SWEAR_LANGUAGE WSC_FOREIGN_WORDS WSC_ANGLICISM_AND_ALTERNATIVE
French/ Canadian French: WSC_RACE_AND_ETHNICITY_INSULTS WSC_STRONG_SWEAR_LANGUAGE WSC_FOREIGN_WORDS WSC_ANGLICISM_AND_ALTERNATIVE
Portuguese: WSC_RACE_AND_ETHNICITY_INSULTS WSC_STRONG_SWEAR_LANGUAGE WSC_FOREIGN_WORDS WSC_ANGLICISM_AND_ALTERNATIVE
Ukrainian: WSC_ANTYSURZHYK WSC_STRONG_SWEAR_LANGUAGE WSC_ANGLICISMS
Italian: WSC_BLASPHEMY WSC_STRONG_SWEAR_LANGUAGE WSC_RACE_AND_ETHNICITY_INSULTS
Dutch: WSC_BLASPHEMY WSC_STRONG_SWEAR_LANGUAGE WSC_RACE_AND_ETHNICITY_INSULTS
For custom rules that can be created by the on-premises clients, the category IDs are the file names UPPERCASED with no extension.
Whereas a rule ID is a unique identifier generated by the server automatically at the time the file is read. It can be learned from the Web API response as ‘rule’ or via browser’s development tools, specifically, inspect element under the ‘data-grammar-rule’. It will have the following format: PREFIX +underscore(_) + up to 20-digit number based on the rule’s pattern. Here is the example of rule ID from the JSON response: "WSC_2664667314028094467".
Also, in the ‘disabledRules.json’ file you can find a list of style rules that disabled by default following the feedback of our customers.
1.3. Disabling specific rules or rules categories for cloud and standalone version v.5.29.0.0 (client-side)
Also you can disable specific rules or rules categories using the disabledRules option on client-side by passing it into your HTML:
For example, if you want to disable all rules that are added by default, you have to specify the following:
1.4. Using Web API to manage style guide feature for cloud and standalone version v.5.29.0.0
Starting WebSpellChecker version 5.29.0.0, we introduce a range of powerful enhancements to our Web API. These enhancements apply to both the Cloud and Standalone versions, allowing you to effectively manage style guide functionality, including the ability to disable specific rules and their categories. Here are the three new API parameters at your disposal:
disable_style_guide=true. This parameter allows you to completely disable the style guide feature.
disabled_rules=RULE_ID_1,RULE_ID_1. With this parameter, you can selectively disable individual rules by providing a comma-separated list of rule IDs. This applies to both style and grammar checks, empowering you to fine-tune the spell checking behavior as per your requirements.
disabled_categories=CATEGORY_ID_1,CATEGORY_ID_1. Similarly, this parameter enables you to disable specific rule categories by specifying a comma-separated list of category IDs.
Please refer to our comprehensive manual for a detailed guide on how to leverage Web API and these parameters effectively.
2. Creating custom rules for on-premises clients v.5.29.0.0+
WebSpellChecker’s Style Guide functionality allows on-premises clients to create a set of rules to mark a specific piece of text as a style error and optionally provide a list of replacements along with a descriptive message.
2.1. Limits and requirements
Limitations
Style guide rules have the following restrictions:
Rules per file: Maximum 2,000 rules per CSV file
File size: Maximum 5 MB per file
File format: Must be
.csvformatFiles per directory: Maximum 50 files per language directory
Forbidden characters: The following characters are not allowed:
[]<>{}\\n\\t\\b\\r\\a\\f\\vSemicolon usage: Semicolon (
;) is reserved as a separator for multiple patterns/suggestions and cannot be escapedComma restrictions: Commas are forbidden in patterns, suggestions and context columns. In descriptions, commas are allowed but the entire description must be enclosed in double quotes (
"")Pattern requirements:
Patterns cannot be empty in a rule
Rules with identical patterns are not allowed
Column length limits:
Patterns: Maximum 150 characters per rule
Suggestions: Maximum 150 characters per rule
Description: Maximum 200 characters per rule
Context to include: Maximum 150 characters per rule
Context to exclude: Maximum 150 characters per rule
Example with comma in the description:
Best practices
Use descriptive file names that clearly indicate the purpose of the rules
Organize rules by scope (common vs. language-specific)
What will happen if you reach some of the mentioned limits?
The behavior for reaching the file size limit is as follows:
If the file is already larger than the limit when AppServer is booting up, it is not read.
If it overshot the limit at runtime, rules are not updated internally. Old ones are still used. The file is not reloaded until it’s of an appropriate size.
The behavior for reaching the file number limit is as follows:
If there are more than 50 files at the start of the server for the language, none are loaded.
If some number of new files are added during the work of the app, no new files are used, until the total number is 50 or fewer. Old (already loaded) files will continue to work as before. Moreover, their edits will also be readily applied.
2.2. How to create custom rules?
To create a custom rule, on-premises clients have to follow the steps below:
1. Navigate to the StyleGuide directory: <Installation_Path>\WebSpellChecker\AppServer\StyleGuide
2. Create the folder with the name company
3. Navigate inside the company folder that is available by default starting v.5.29.1.0, and create another folder with the name that will relate to the language alias that you can find in the AppServerX.xml file. For example, en for English.
If there are two aliases in the AppServerX.xml file, you can use any of them.
4. Create a .csv file inside the created folders following the requirements described above. For example, the `mycompany_example.csv` file inside:
<Installation_Path>\WebSpellChecker\AppServer\StyleGuide\company\en
The file name is meaningful. It consists of two parts:
The first is the text before the first underscore (_). It will be used as a “prefix” or “namespace” for all rules and categories you create. Conveniently, it can be the name of your company or organization, or a variation thereof.
The second part is the rest of the text after the first underscore (which itself can contain other underscores). It stands for a category name for this rule set. Categories are logical groupings of your rules.
Custom rules categories can be multilingual. Thus, files
StyleGuide/company/en/mycompany_example.csv
StyleGuide/company/de/mycompany_example.csv
will add rules for the same category in two different languages (English and German, respectively). This is important to keep in mind, because when you disable a category, it applies to all the languages it’s defined for.
5. Inside .csv we define rules in the following way:
Input — Original text (TAB for several instances);
Output — A substitute for the original text. Can be empty — no substitute;
Message — Explanation (360 characters).
All the changes inside StyleGuide/company are live automatically.
mycompany_example.csv
How it will look like using WProofreader:
Still have a question?
Please feel free to contact our technical team if you are having any difficulties with the configuration.
Last updated
Was this helpful?