Configuring Rule Sets

This section explains about Rule Sets and describes the procedure for creating and editing Rule Sets. It discusses the following topics:

What are Rule Sets?
Logging into the Server
Creating New Rule Sets
Editing Rule Sets
Enabling/Disabling Rule Set Categories
Copying Rule Sets
Deleting Rule Sets

What Are Rule Sets?

A Rule Set is of a set of parameters that the Globalyzer Client scanner uses to detect internationalization issues and generate Scan Results.

A Rule Set is divided into five scanning categories: Source File Extensions, Embedded Strings, Locale-Sensitive Methods, General Patterns, and Static File References. Within each category, there are Detection or Retention Rules and Filtering Rules.

Detection Rules specify internationalization issue conditions that the Globalyzer source code scanner will detect and report to you. All detection categories (except for Embedded Strings) are accessible to Globalyzer users for altering, adding to and deleting.

Filtering Rules specify conditions that the scanner will overlook. For instance, by default, Globalyzer detects embedded strings. Embedded string detection is a fixed part of each Rule Set that you create (you cannot edit the embedded string rules). However, some strings embedded in your code are not intended for display to an end user and hence, should not be included in Globalyzer's reports listing strings that need to be externalized for translation.

Retention Rules are for embedded strings only and specify conditions upon which strings should be retained.

Applying Detection and Filtering Rules

For all Scans, except the Embedded String Scan, there is only one type of Detection Rule to find issues, and then many types of Filtering rules to apply to each detection. The final list of issues is everything that was detected that wasn't later filtered.

In the case of Embedded Strings, Globalyzer first detects all the strings in the file, and then applies rules in the order shown below. We have ordered Filtering and Retention Rules so that specific filters and patterns are applied before more general filters and patterns. For example, a string might be a parameter to a method that is in a line that is part of a statement. So, if you defined a String Method Pattern to retain an issue, but you have a String Statement Filter that filters the statement, the issue will ultimately be filtered since the more general, String Statement Filter, is applied last.

Order for most Rule Sets

String Content Filters
String Content Patterns
String Variable Filters (if applicable)
String Variable Patterns (if applicable)
String Method Patterns (if applicable)
String Method Filters (if applicable)
String Line Filters
String Statement Filters (if applicable)

Order for HTML Rule Set

Ignored HTML Tags
Included HTML Tags
String Content Filters
String Content Patterns
String Line Filters
String Concatenation Patterns

Source File Extensions

Detection: Source File Extensions

This category simply tells Globalyzer which source files to scan if you point it at an entire directory of source files.

Filtering: File Extension Filters

Filters allow you to exclude files and directories from being scanned. For example, you may not want to scan files in test directories. Via a filter, you can tell Globalyzer to skip all files with the directory test in its path.

Embedded String Scan Rules

Filtering: String Content Filters

Embedded strings that shouldn't be externalized may be programmatic elements or debug messages printed to the console. Globalyzer provides several ways to filter such strings from your scan results. The first way is to specify a pattern, which if Globalyzer detects within a string literal, will cause Globalyzer to ignore that string. This mechanism is called String Content Filters.

Filtering: String Variable Filters

Another mechanism for filtering strings is called String Variable Filters. Your code likely contains strings that are compared or assigned to variables that you know will never be displayed to an end user. For example, in XML there are attribute strings, such as column="status". If you configure column as a String Variable Filter, the string "status" will be filtered.

Filtering: String Method Filters

The second mechanism for filtering strings is called String Method Filters. Your code likely contains many method or functions that are passed string arguments. When you are sure that any string passed into function X is never displayed to the user, you can specify that function name within the String Method Filters rules and whenever Globalyzer sees that a string literal is passed as an argument to any of the methods, functions, or constructors in this list, it will ignore those strings.

For example, the Java method:

javax.servlet.http.HTTPServletRequest.getParameter(String s)

takes a string argument, but this string would never appear as text visible to an end user. Therefore, if you add this method (method name only) to the list of String Method Filter rules, Globalyzer will ignore any string literal passed in.

Filtering: String Line Filters

Another mechanism for filtering embedded strings is called String Line Filters. In the case where there are strings that will never be displayed to the user and reside in lines of code that share a specific string pattern, you can add that pattern to the String Line Filter rules. Whenever Globalyzer detects string literals in a line of code that also contains one of the patterns in this list, it will ignore those strings.

For example, suppose you have several strings defined that are used only in conditionally compiled debug code:

String szName = "Name"; // Debug String szStart = "Start";// Debug String szEnd = "End"; // Debug String szTime = "Time"; // Debug

Since these are all common words, it would be difficult to eliminate them from the embedded string report using String Content Filters. However, since each line of code also contains the comment Debug, we can add that shared pattern to the String Line Filter rules. Now, when Globalyzer scans for string literals, it will find a matching pattern in the String Line Filters rules for these four lines, and thus filter the four string literals from the embedded string report.

Filtering: String Statement Filters

For languages that support the notion of statements (Java, JavaScript, C#, etc), another mechanism for filtering embedded strings is called String Statement Filters. If Globalyzer detects a string literal within the same statement as a defined pattern, that string will be excluded from the Embedded String Scan Results.

For example, set up a String Statement filter for the pattern idioms and scan the following:

var idioms = ["haste makes waste", "so far so good", "speak of the devil"];

The string statement filter will find idioms and filter all three strings within the statement.

Filtering: Ignored HTML Tags

For HTML projects only, users will see the Ignored HTML Tags category. This category requires special explanation and has a section dedicated to it. Please read this section if you intend to customize.

Retention: Included HTML Tags

For HTML projects only, users will see the Included HTML Tags category. This category requires special explanation and has a section dedicated to it. Please read this section if you intend to customize.

Retention: String Content Patterns

String Content Patterns helps you add conditions under which strings that would normally be filtered, stay in the Scan Results. It is basically an override of the different string filters. For example, normally strings where the first word starts with a special character such as @ are filtered out, but your product name is @Large, so naturally you want strings beginning with @Large to still be caught.

Retention: String Variable Patterns

String Variable Patterns ensure that strings compared or assigned to configured variables stay in the Scan Results, even if they would normally be filtered. For example, normally strings where the first word starts with a special character such as @ are filtered out. However, if this special character string is assigned to a variable named DisplayStringToUser, then the string should still be caught.

Retention: String Method Patterns

String Method Patterns ensure that strings passed to configured methods stay in the Scan Results, even if they would normally be filtered. For example, normally strings where the first word starts with a special character such as @ are filtered out. However, if this special character string is passed to the method MessageBox(), then it most likely will be displayed to the end user and should still be caught.

Retention: String Concatenation Patterns

For HTML projects only, users will see the String Concatenation Patterns category. Globalyzer detects concatenations in HTML strings. If a string would normally be filtered (for example, the string is a series of externalized text, or maybe the string contains text and server-side code, but the text is not in the Dictionary), String Concatenation Patterns will be applied and potentially make the string Active with priority C. This enables finding concatenations in HTML strings that have already been externalized in parts, rather than as a whole.

Locale-Sensitive Method Scan Rules

Detection: Locale-Sensitive Methods

The Locale-Sensitive Methods category includes rules used to detect method calls, functions, and constructors in your source that are potentially locale-sensitive within certain locales and for certain character encodings. The methods are organized into groups. The Globalyzer user can create new groups and/or add new methods to groups. This category is programming language dependent and so is not available for all programming languages. An example of such a rule is Java's lang.String.ToLowerCase() method. This signature draws upon the rules of the default locale to convert a string to lower case. The rules of the default locale would not be correct for languages in all locales, some of which do not have a lower-case mode to their alphabets.

Note: When Globalyzer scans code for locale-sensitive methods, the All Predicted Scan Summary generated by Globalyzer includes links for all detected locale-sensitive methods. The link takes you to information about how to refactor or replace the detected method to make your code function properly across all locales and character encodings.

Filtering: Method Line Filters

Method Line Filters are similar to String Line Filters, but apply to the Locale-Sensitive Methods detection category. Whenever Globalyzer detects a locale-sensitive method in a line of code that also contains one of the patterns in this list, it will ignore the method.

General Pattern Scan Rules

Detection: General Patterns

Users can alter, add to and delete from the General Patterns category, which can include any regular expression that the user wants the scanner to look for during the scan. This might include patterns used to enforce coding standards or anything at all -- not necessarily internationalization-related patterns.

Filtering: General Pattern Line Filters

General Pattern Line Filters are the line filters for the General Patterns scanning category. Whenever Globalyzer detects a general pattern in a line of code that also contains one of the patterns in this list, it will ignore the general pattern detection.

Static File Reference Scan Rules

Detection: Static File References

This category is used to detect image and other static file paths in source code. During the internationalization process, these static files need to be localized and placed in locale-specific directories. All paths to those localized files in the source code must then be altered to retrieve and load the localized file at run time from the locale-specific directory corresponding to the user's locale.

Filtering: Static File Filters

Static File Filters apply to the Static File References detection category. Globalyzer will ignore the static file if it contains one of the patterns in this list.

Filtering: Static File Line Filters

Another mechanism for filtering static file references is with the Static File Line Filters. In this case, Globalyzer will ignore the static file if it is in a line of code that also contains one of the patterns in this list.

Logging into the Server

Rule Sets are typically configured on the Globalyzer Server, using a browser. The first step is to log into your account on the server. Click here for detailed login instructions.

Creating New Rule Sets

Rule Sets can be created as base Rule Sets or inherited Rule Sets. Base Rule Sets are created with a set of default rules defined on the server. Inherited Rule Sets extend an existing Rule Set; they inherit all the rules of the parent Rule Set and can add new rules and/or override inherited rules. When rules are added, modified, or deleted in the parent Rule Set, those changes are inherited.
Click here for more information on Rule Set Inheritance.

Creating a base Rule Set

To create a Base Rule Set:

Log into the server.

From your home page, select Create Rule Set. The Create Rule Set page appears.

Enter a name for the new Rule Set.

From the Language - Variant list, pick the type of source code that you wish to scan. The language-variant choices are:

The variant determines the default set of Locale-Sensitive Methods for the Rule Set. Click here for more information on Rule Set languages and variants.

Check the Shared box if you want team members to be able to use your rule set to scan their source code using the Globalyzer Client.

Click the Create button.

The Customize Rule Set page appears.

This page allows you to edit the default settings for the five scanning categories. Click on a link below for detailed information about configuring each type of rule.

Source File Extensions

Source File Extensions
Choose from and add to a list of file extensions to determine what types of files will be scanned within a chosen project directory.

File Extension Filters
Choose from and add to a list of default patterns that specify file names and directories to exclude from scanning.

Embedded String Scan Rules

String Content Filters
Choose from and add to a list of default strings to filter out of the Embedded String code scan.

String Method Filters
Choose from and add to a list of methods to use to filter strings passed as parameters out of the Embedded String code scan.

String Variable Filters
Choose from and add to a list of variables; strings compared/assigned to these variables will be filtered from the Embedded String code scan.

String Line Filters
Choose from and add to a list of default patterns to filter code lines out of the Embedded String code scan.

String Statement Filters
Choose from and add to a list of default patterns to filter code statements out of the Embedded String code scan.

Ignored HTML Tags
Choose from and add to a list of tags that are filtered as part of the embedded text when the HTML scanner is searching for text between matching tags.

String Content Patterns
Create Regular Expressions that will override any String Filter, ensuring that strings with these patterns will remain in the Scan Results.

String Method Patterns
Choose from and add to a list of methods that will override any String Filter, ensuring that strings passed as parameters to these methods will remain in the Scan Results.

String Variable Patterns
Choose from and add to a list of variables that will override any String Filter, ensuring that strings compared/assigned to these variables will remain in the Scan Results.

Included HTML Tags
Choose from and add to a list of tags that are included as part of the embedded text when the HTML scanner is searching for text between matching tags.

String Concatenation Patterns
Choose from and add to a list of patterns that will be applied to the concatenations Globalyzer has found that are currently Filtered. This enables HTML strings that contain concatenations to be included in the list of Active Scan Results, even though the strings themselves do not contain text in need of externalization.

Locale-Sensitive Method Scan Rules

Locale-Sensitive (Unsafe) Methods
Choose from and add to a list of default locale-sensitive methods to identify in the Locale-Sensitive Method code scan.

Method Line Filters
Choose from and add to a list of default patterns to filter code lines out of the Locale-Sensitive Method code scan.

General Pattern Scan Rules

General Patterns
Choose from and add to a list of patterns to include in the General Patterns code scan.

General Pattern Line Filters
Choose from and add to a list of default patterns to filter code lines out of General Pattern code scan.

Static File Reference Scan Rules

Static File References
Choose from and add to a list of default static file extensions to identify in the Static File Reference code scan.

Static File Filters
Choose from and add to a list of default patterns to filter static file references out of the Static File Reference code scan.

Static File Line Filters
Choose from and add to a list of default patterns to filter code lines out of the Static File Reference code scan.

Creating an inherited Rule Set

To create an inherited Rule Set:

Log into the server.

From your home page, select either My Rule Sets or My Team Rule Sets. The appropriate Rule Sets page displays.

Click on the name of the Rule Set you wish to extend. The rule set could be one you, or a team member, created. The Customize (or View) Rule Set page displays. Click the Extend button at the bottom of the page. This displays the Extend Rule Set page, shown below.
Give the new Rule Set a name in the Extend Rule Set page, and click the Save button.

The Customize Rule Set page appears for your new Rule Set.

The Customize Rule Set page allows you to edit the default settings for the five scanning categories, as described above.

Editing Rule Sets

To edit an existing Rule Set:

From your home page, select My Rule Sets. The My Rule Sets page appears.

In the My Rule Sets page, click on the name of the rule set you wish to edit. This displays the Customize Rule Set page for the rule set. Edit the current settings for the five scan rule categories by clicking on the various links.

Click the Edit button at the bottom of the page to modify the name, shared status of the rule set, assigning ownership to another user, and most importantly to disable/enable rules based on category.

For example, above is a Javascript rule set with multiple categories based on popular JS frameworks. All rules labeled by specific categories in this rule set can be bulk enabled/disabled with this feature below. This allows a user to enable certain rules if they are using a specific framework, or just want to group certain rules by category for unique projects.

Enabling/Disabling Rule Set Categories

To enable or disable rules of a Rule Set based on category:

As described above: log in to the server, select My Rule Sets, click on the name of the rule set you would like to edit, and click the edit button on the bottom of the page.

From this page, you can enable or disable rules based on their respective categories. Select a drop-down menu as seen below, where a user can enable all, disable all, or leave all rules based on that category unchanged.

NOTE: These categories relate to the category column within a rule set group as seen below:

Copying Rule Sets

To copy an existing Rule Set:

From your home page, select either My Rule Sets or My Team Rule Sets. The appropriate Rule Sets page displays.

Click on the name of the rule set you wish to copy. The rule set could be one you, or a team member, created. The Customize (or View) Rule Set page displays. Click the Copy button at the bottom of the page, as shown in the image above. This displays the Copy Rule Set page, shown below.
Give the new Rule Set a name in the Copy Rule Set page, and click the Save button.

Deleting Rule Sets

To delete an existing Rule Set:

From your home page, select My Rule Sets. The My Rule Sets page appears.

In the My Rule Sets page, click on the name of the rule set you wish to delete. This displays the Customize Rule Set page for the rule set. Click on the Delete button at the bottom of the page.

User's Guide Contents