jsRealB - A JavaScript Bilingual Text Realizer for Web Development
Version 3.7 - April 2021
Natural Language Generation (NLG) is a field of artificial intelligence that focuses on the development of systems that produce text for different applications, for example the textual description of massive datasets or the automation of routine text creation.
The web is constantly growing and its content, getting progressively more dynamic, is well-suited to automation by a realizer. However existing realizers are not designed with the web in mind and their operation requires much knowledge, complicating their use.
jsRealB is a text realizer designed specifically for the web, easy to learn and to use. This realizer allows its user to build a variety of French and English expressions and sentences, to add HTML tags to them and to easily integrate them into web pages.
jsRealB can also be used in Javascript application by means of a node.js
module available also as npm
package. It also accepts an input specification in JSON.
The documentation can be accessed here. You can switch language in the upper right corner of the page. The specification of the JSON input format is described here.
Caution
jsRealB
can be used (out of the GitHub!) in a web page using onlyjsRealB.min.js
(orjsRealB.js
) in thedist
directory.node.js
is necessary for the Javascript applications and for minifying the Javascript usingterser
.- The current build process relies on the availability of some Unix tools such as
makefile
,cat
and output redirection (>
). - Windows users (and others) will therefore want to use the pre-built files in the
dist
directory.
Directories
Architecture
:README.md
: Description of the architecture of the system; the second section goes into details of the organization of the source files and describes the main methods.
build
: build system to create the JavaScript library; more details in the document on the architecture of the systemConstituent.js
: Constituent is the top class for methods shared between Phrases and TerminalsDate.js
: utility functions for dealing with date formattingIO-json.js
: functions for dealing with the JSON input formatjsRealBclass.py
: Python classes and functions to generate the JSON input format and use jsRealB from Pythonmodule-end.js
: lines to add at the end when creating a module from js filesmodule-exports.js
: list of exported identifiers when creating a module from the js filesmodule-start.js
: line to add at the start when creating a module from js filesNumber.js
: utility function for dealing with number formattingPhrase.js
: subclass of Constituent for creating complex phrasesswi-json.pl
: SWI-Prolog predicates to create the JSON input formatTerminal.js
: subclass of Constituent for creating a single unit (most often a single word)Utils.js
: useful functions that do not belong to the constituentsWarnings.js
: list of functions to generate warnings in case of erroneous specifications using jsRealB itself
data
:lexicon-en.js
: basic English lexicon (5238 entries) [preloaded]rule-en.js
: English conjugation and declension tables [preloaded]lexicon-fr.js
: basic French lexicon (3720 entries) [preloaded]rule-fr.js
: French conjugation and declension tables [preloaded]lexicon-dme.json
: a comprehensive English lexicon (33926 entries) in json formatlexicon-dmf.json
: a comprehensive French lexicon (52512 entries) in json formatlexicon.jsonrnc
: JSON-RNC file for validating a lexiconlexiconFormat.html
: documentation of the format of the lexiconjsRealB.jsonrnc
: JSON-RNC file for validating the JSON input specificationjsRealB.jsonrnc.json
: json version of JSON-RNC file for validating the JSON input specification (generated by the parser of the input)jsRealB-jsoninput.html
: documentation of the format of the JSON input specification
- [
demos
] : see next section dist
: pre-built JavaScript files ready for production use, they already include the basic English and French lexicons and the English and French rule tables- For use in a web page :
<script src="..."></script>
jsRealB.js
: packages all .js files of thebuild
directory as a module and exports only the main functionsjsRealB.min.js
: minified version of the above
- For use as a node.js module :
jsRealB-node.js
: packages all .js files of thebuild
directory as a module and exports only the main functionsjsRealB-node.min.js
: minified version of the above
jsRealB-filter.js
: example of use of the node.js module to create a Unix filter forjsRealB
jsRealB-server.js
: example of use of the node.js module to start a web server that realizes sentencesjsRealB-server-dme.js
: same as above but loading the comprehensive lexicontestServer.py
: example of a Python program using thejsRealB
serverdatedCore.js
: intermediary file used during the makefile for saving the date the makefile was created. This file should probably be deleted after the makefilepackage.json
: necessary for publishing thejsrealb
npm package.
When a new version is to be put onnpm
, in principle, it should be enough to issue the two following commands from within thedist
directory:
npm version {major|minor|patch}
npm publish
Because of the.npmignore
hidden file in this directory, onlyjsRealB.js
andjsRealB.min.js
are published.
- For use in a web page :
documentation
: in both English and French. The examples are generated on the fly by embeddingjsRealB
in the page. Consult the documentationjsRealBfromPython.html
: documentation for creating the JSON input format in Pythonuser.html
: HTML of the core of the page (div[id]
correspond to variables inuser-infos.js
)style.css
: style sheetuser-infos.js
: definitions of variables containing the examplesuser.js
: JavaScript helper script.
IDE
: An Integrated Development Environment built upon theNode.js
read-eval-print loop that includesjsRealB
to easily get the realization of an expression, to consult the lexicon, the conjugation and declination tables. It is also possible to get a lemmatization: i.e. thejsRealB
expression corresponding to a form. See theREADME.md
file to learn how to use it.Tests
: unit tests (using QUnit) of jsRealB in both French and English.testAll.html
: load this file in a browser to run all tests
- jsRealB Tutorial. Read the tutorial
- Files in the current directory:
jsRealB2.html
: simplistic web page that loads each Javascript file from thebuild
directory; this is very useful for testing using the Javascript inspectorjsRealB2-min.html
: simplistic web page that loadsdist/jsRealB.min.js
; this is very useful for testing that the minified file still worksjsRealB2.js
: some test sentences that are displayed on the console when loading the above filemakefile
: for building files in the dist and managing the systemREADME.md
: this file
Demos
Simple examples on a single sentence
- Evaluate a
jsRealB
expression and display its realization in a web page in either English or French. - Show the use of loops in Javascript to create repetitive texts
- English: 99 bottles of beer. Execute
- French: 1 km à pied. Execute
- Tests of specific features
-
French and English sentences modified with time, number and conjugation: Date generation Execute
-
Type a French or English sentence that will be realized with all possible sentence modifiers Sentence variants Execute
-
French or English conjugation and declension of a word Conjugation and declension Execute
-
Generate a table (both in English and French) showing the different forms of pronouns
- using the original specification
- using the tonic and clitic options
This table is now part of the documentation
-
- User interface to create a simple sentence with options. The system shows the
jsRealB
expression and its realization. It is also possible to ask for a random sentence using words of the lexicon. - Generate spelling and grammar exercises from a simple sentence structure in both English and French.
jsRealB
is also available an annpm
package:use-npm.js
is a simple example of its use (after it is installed on the system)
Text realization
- Create an Exercise in Style which creates the structure of the original story of Raymond Queneau in both French and English. Using menus, some elements of the text can be modified and the modifications are highlighted in the web page. Exercises in style Execute
- Generate a text in French for asking a pay raise following a flowchart as originally described by George Perec. Using menus, some elements of the text can be modified. The path in the flowchart is displayed in the web page and it is possible to highlight a step in the flowchart with the corresponding text. L'Augmentation Execute
- Regenerate a sentences from the information contained in its Universal Dependencies structure:
- in English : Execute
- in French : Execute
- Paper describing the approach
- Reproduce a classical fairy tale in which hovering over a sentence, shows the underlying
jsRealB
expression
Data to Text applications
-
jsRealB
for the E2E Challenge : browser for the datasets (training, development and test) used in the End to End Generation Challenge (2017-2018). The page also shows the English and French output produced by a "rule-based" generator usingjsRealB
for a selection of feature values. There is also a short description of the implementation of the realiser. Execute -
Description (in French) of a list of events and associated informations given as a json file Événements Execute
-
Description of list of steps for the building of a house, given information about tasks, the duration and the precedence relations between them.
The system first computes the critical path to find the start and end times of each task. It then creates a graphic for displaying the PERT diagram and an accompanying text to explain the steps to follow. It is possible to interactively change the start date and to explore the graphic with the mouse which also uses jsRealB to generate the text of the tooltips.
-
Itinerary description in an optimistic Montréal Métro network. The system shows an interactive map of the Montréal Métro station with a new line. When a user clicks two stations, the systems realizes a text describing the itinerary to go from the first station to the second.
The langage of the web page and of the realization can be changed interactively by clicking in the top right of the page. Metro Execute
Test demos
- The demos are usually run using the compiled version. But after modification of the source files, the version with the separate loading of the file can be obtained by commenting/uncommenting some
<script>...</script>
lines at the start of the html file. The shell scripttestDemos.sh
can be used to do this while keeping the original intact. If the script is called with a name of an HTML file, then that file is uncommented and shown in the browser (using theopen
command on the MacOS). With no argument, then all demos are displayed in different tabs. The script wait for 5 seconds between each try.
Interactive use with Observable
- Two Observable notebooks are available for trying
jsRealB
expressions and seeing their realizations.
Design of the system
The current version (3.7) is a redesign and reimplementation of the previous version while keeping intact the external interface, i.e. same name of functions for building constituents, for option names and for global functions. This means that applications using only the external interface of jsRealB
can be run unchanged.
This document first describes the transformation steps within the realizer using a few examples. It then gives an overview of the implementation explaining the role of the main classes and methods.
Authors
jsRealB was updated, developed and brought to its current version by Guy Lapalme building on the work of:
- Francis Gauthier as part of his summer internship at RALI in 2016;
- Paul Molins as part of an internship from INSA Lyon spent at RALI, University of Montreal in 2015;
- Nicolas Daoust developed the original concept in the JSreal realizer for French only in 2013.
For more information, contact Guy Lapalme.