How to Localize the Business Action Language

Samples > Rule Studio Authoring Extensions > How to Localize the Business Action Language

How to Localize the Business Action Language

This sample shows how to localize the Business Action Language (BAL) to enable you to write rules and decision tables in the localized language. To localize the BAL, you must:

Translate the boot vocabulary file for the core data types
Translate the files that describe the BAL concrete syntax and localized unambiguous regular expressions used to parse and render numbers, dates and time literal values.
Create a verbalizer for this language. The default verbalizer supplied with ILOG Rule Studio is for English.

A verbalizer builds human-readable terms and phrases for the concept and fact types of the vocabulary. In particular, the verbalizer proposes default values for the plural forms of a term, assembles the articles and terms to build default phrases for action and navigation fact types.

Key Features

Key features include:

Installation and registration of a localized BAL in Rule Studio.
Implementation of IlrVerbalizer interface, IlrTermBuilder, IlrArticleBuilder and IlrPluralBuilder interfaces.

Installing this Sample

This sample extends the Rule Studio API. The required sample plug-ins are delivered as pre-deployed. If you have not already done so, you must install the samples extension site in Eclipse before running this sample.

This sample uses Spanish as the localized language. This is for illustration only, and is not officially supported.

To install the plug-in samples extension site:

Click Help > Software Updates > Manage Configuration.
In the Product Configuration dialog, click the Add an Extension Location link.
In the Browse dialog, select the folder <InstallDir>/studio/samples/eclipse.
If prompted to restart the Eclipse Workbench, click Yes.

Eclipse shuts down and restarts.

To check that the Spanish Business Action Language Sample feature is enabled:

Click Help > Software Updates > Manage Configuration.
In the left pane of the Product Configuration page, expand C:\ILOG\JRules\studio\samples\eclipse and check that Spanish Business Action Language Sample 1.0.0. is listed.

To import the carrental_es sample:

Click File > Import.
In the Import Wizard, select ILOG Rule Studio Samples and Tutorials.
Click Next.
On the Sample or Tutorial page, select the sample authoring > carrental_es.
Click Finish.
If one or more files already exist in your workspace, a warning message is displayed indicating the file(s) were not re-imported. Close the message window.

The imported sample project files are displayed in the Rule Explorer. You should see two new projects:

- carrental-es-xom. A Java project containing an execution model. The class and member names in this XOM are in Spanish.

- carrental-es-rules. This project contains rules written with the spanish BAL, using a vocabulary on top of the BOM created from the Spanish XOM.

Running this Sample

You will start by exploring and running the sample, then restarting Rule Studio in a Spanish locale. You will then explore and run the sample in Spanish, then create a second BOM entry from the XOM.

To explore and run the sample:

In the Rule Explorer, expand the rule project carrental-es-rules and open and examine one or more of its rules.

Notice how BAL keywords, expressions, and the options offered in the rule completion menus are all provided in Spanish.

Click Run > Run.
Select the carrental_es launch configuration, then click Run.

A simple ilrmain function runs the rules for a simulated input parameter. The Spanish rules are translated into correct IRL syntax, independently of the locale in which the rules are executed.

To restart Rule Studio in a Spanish locale on UNIX:

Open the <InstallDir>/shared/bin/build.xml file.
Add the parameter -nl es to the Eclipse launcher command line.
Restart Eclipse.

To restart Rule Studio in a Spanish locale on Windows:

Click Run > Run.
Select the Run-time Workbench > spanish-rule-studio launch configuration, then click Run.

A new run-time instance of Eclipse is started and is configured with the Spanish locale.

Re-import the carrental_es sample, as described in the Installing this Sample section.

To explore and run the sample in Spanish:

Create and author a new BAL rule in Spanish. For example, recreate an existing rule.

You will see a localized BAL in action.

Save and close the rule.

To create a second BOM entry from the carrental-es-xom XOM:

Right click the bom folder in the carrental-es-rules project and click New >BOM Entry.
In the New BOM Entry dialog, click Create a BOM Entry from a XOM, then click Next.
Click Browse XOM and select the carrental-es-xom XOM.
Select all classes, then click Finish.
Examine the default verbalization for any of the selected classes and notice the effect of a localized verbalizer.

Source Files

To display the source code of the bal_es Eclipse plug-in:

Click File > Import.
In the Import Wizard, select External Plug-ins and Fragments and click Next.
In the Import As section, select the Projects with source folders option and click Next.
In the Plug-ins and Fragments Found list, select the plug-in ilog.rules.studio.samples.bal_es.

Be careful not to select ilog.rules.studio.samples.bal_es.source.

Click Add.
Click Finish.

The source code of the plug-in is imported and appears in the Rule Explorer.

Switch to the Plug-in Development perspective.
In the Package Explorer, navigate to the Java source files in the folder ilog.rules.studio.samples.bal_es > src-bal_es.

The following source files are of interest and described in Highlights:

IlrSpanishVerbalizer
IlrSpanishUtil

Highlights

BAL concrete syntax message files must be stored using the ISO-8859-1 encoding:

bal_es.properties: Translations for main BAL keywords: "definitions", "if", "then", "else", and so on
dt_es.properties: Translations for decision table specific keywords and definitions.
balexpr_es.properties: Translations for BAL expressions such as "there is/are ...", "the number of", "all of the following conditions are true", "any of ..."
expr_es.properties: Translations for expressions such as "where", "in/from",
brl_es.properties: Localized regular expressions to parse and render numbers, dates and time literal values, and translations for warnings and error messages
bindings_es.properties: Translations for the expressions used to write definitions
actions_es.properties: Translations for the expressions used to write actions

The Spanish boot vocabulary file must be stored using the UTF-8 encoding:

boot_es.voc: Translations for basic terms, fact types and operators: boolean, numbers, strings, dates, times

The IlrSpanishVerbalizer class extends the IlrDefaultVerbalizer general-purpose verbalizer class:

The verbalize method concatenates the appropriate article (depending on the verbalization context) with the term label (possibly using a plural form)
The getSupportedGenders and getDefaultGender methods declare the possible and default genders used in a language, respectively. In Spanish, for example, nouns are either masculine or feminine, and the default value is masculine.
All the methods used to build templates for fact types are implemented: getGetterTemplate / getSetterTemplate to access a regular member, getPredicateGetterTemplate / getPredicateSetterTemplate to access a boolean member, getCollectionAddTemplate / getCollectionRemoveTemplate to modify a collection
Results of all these methods are processed with idiomatic rules implemented in the IlrSpanishUtil class.

The IlrSpanishArticleBuilder class returns articles for all possible genders, in both singular and plural forms.

The IlrSpanishTermBuilder class creates a term from a string source, using the IlrSpanishUtil class to try to adapt the default label to Spanish specific conventions, and guess the gender of the term.

The IlrSpanishPluralBuilder class also uses the IlrSpanishUtil class to return the plural form of a term or a fact type.

The IlrSpanishUtil class deals with a certain number of idiomatic rules and conventions (it can be extended further to cover more rules):

Coding conventions: Not all characters available in a language's alphabet can be used in the name of a Java class or member. Instead, developers use naming conventions to `encode' these characters in simple ASCII. For example, in Spanish, `ny' is used in Java to refer to the letter `ñ'. When such a class is used in a BOM and verbalized, the 'ny' sequence should be replaced by `ñ'.
Accentuation: In Spanish, depending on the last letter of a word, the tonic accent can be determined without a written sign. Exceptions require a written accent to set the tonic. In some cases, there are patterns that can be used to determine this kind of exception. For example, words ending with `-on' generally have the tonic on the last syllable, and require an accent on the last `o'.
Plurals: In Spanish, there are rules that can be used to build plural forms depending on the last letter(s) of a word. For example, there are rules for words that end with a vowel, words that end with a consonant, words that end with a `z', words that have a written tonic accent on the last syllable, and so on.
Gender: In Spanish, there are rules that can be used to determine the gender of a word depending on the last letter(s) of a word. For example, words ending with `a', `d', `ción', `sión', `zón', and `ez', are generally feminine, though of course there are exceptions.