Aller à ↓Goto ↓ [FREN]

jsRealB (Version 3.4) - Documentation

jsRealB est un réalisateur de texte pour l'anglais et le français écrit en Javascript. Il peut être utilisé soit à l'intérieur d'une page web comme celle-ci dont tous les exemples sont réalisés dynamiquement, ou comme module Node.js.

jsRealB is a text realizer for French and English written in Javascript. It can be used either within a web page such as this one whose examples are dynamically realized or as a Node.js module.

Constituants

Constituents

Les accords simples sont effectués entre les constituants d'un syntagme. Un constituant est considéré comme la tête avec lequel les autres sont accordés. La tête est déterminée de la façon suivante:

Des options (section suivante) spécifiant le genre et le nombre l'emportent sur ces accords automatiques.

Simple agreements are dealt with between constituents of a phrase. A constituent is taken as the head with which others agree. The head is found as follows:

Options (next section) can override these automatic agreements.

Déclinaisons et conjugaisons

Declension and conjugation

Perfect and continuous tenses for verbs can obtained by setting the sentence type to .typ({perf:true}) or .typ({prog:true})

Pronoms

Pronouns

Le pronoms qui sont dans le lexique sont à la 1ère personne du singulier. Pour obtenir les autres, il faut spécifier la personne, le nombre et éventuellement le genre. Ce mécanisme s'applique aussi pour les pronoms me et moi-même et pour le déterminant mon.

Pronouns in the lexicon are at the first person singular. To get the other forms, the gender, the number and the person must be specified. The same option mechanism can be used for the pronouns mine and myself and for the determiner my.

Pronoms en modifiant la forme tonique Pronouns from the tonic form

Le tableau suivant présente la forme obtenue au-dessus de la spécification jsRealB.

Le tableau suivant présente les pronoms possessifs qui s'accordent en genre et en nombre.

Les déterminants possessifs varient en genre et en nombre à partir de leur forme de base comme le montre le tableau suivant.

The following table shows the realized form above the corresponding jsRealB expression.

Possessive determiners are specified by giving options for the number, the person, the gender (when at the third person) and also if the owner (.ow(..)) is singular or plural. The following table shows the realization above its jsRealB specification.

Mise en forme

Formatting

Si l'ajout avant et/ou après un constituent correspond à un signe de ponctuation défini dans les règles, l'espacement approprié est ajouté avant et après le signe, sinon la chaîne est ajoutée telle quelle sans espacement.

If the content added before and/or a constituent is defined in the language rules, then the appropriate spacing is added before and after the punctuation sign, otherwise the content is added without spacing.

Modification du syntagme nominal

Noun phrase modification

Modification du type de phrase

Sentence type modification

Les phrases sont construites à la forme active, mais il est possible d'en modifier le type pour obtenir des phrases négatives, progressives, interrogatives ou passives. Ces modifications sont de la forme S(...).typ({...}) Il est possible de combiner plusieurs modifications en spécifiant plusieurs paires clés-valeurs dans l'objet paramètre de type. L'utilisation de contractions en anglais telles que I'll pour I will ou can't pour cannot peut aussi être spécifiée de cette manière, mais cet indicateur est ignoré en français.

Sentences are built at the active voice, but their type can be modified in order to get negative, progressive, interrogative or passive sentences. These modifications are indicated by S(...).typ({...}). Modifications can be combined by specifying multiple key value pairs in the object which is the parameter of type. The use of contractions such as I'll for I will or can't for cannot can also be specified in this way. This flag is ignored in French.

Date

Date

DT accepte en paramètre soit une date sous forme d'une chaîne de caractères ou un objet Javascript Date.La chaine de caractères en entrée doit être dans un format reconnu par la méthode Date.parse(), donc dans le format IETF-compliant RFC 2822 ou ISO8601.

Attention: Le comportement de l'objet Date() diffère selon le navigateur. Il est fortement conseillé de fixer le fuseau horaire sinon il sera déterminé par le navigateur (voir ci-dessous).

DT(...) takes as parameter either a date as a String or a Date javascript object.The input string must be a recognized format by Date.parse(): either IETF-compliant RFC 2822 or ISO8601 format.

Warning: The behavior of Date() depends on the browser. The timezone should be specified otherwise it might be given a different value according to the browser.

Nombres

Numbers

On crée un nombre avec NO(...) dont le paramètre est soit un nombre entier ou réel ou une chaîne qui peut être analysée comme un nombre.

A number is created with NO(...) whose parameter is either a number (integer or real) or a string that can be parsed as a number. In English, numbers less than one hundred written in letters can also be used as input.

JavaScript

JavaScript

.clone()

Comme les options modifient le constituant dans toutes les utilisations subséquentes, il est souvent pratique de pouvoir garder la version originale pour la réutiliser et la modifier indépendamment. L'option clone() permet de copier un syntagme pour utilisation dans des contextes différents.

As options modify the constituent for all following use, it is often useful to keep the original constituent and modify it independently. The clone() option allows reusing a constituent in different contexts.

Une alternative à clone() est d'associer une fonction à une variable, ce qui créera une nouvelle expression à chaque appel. Ceci permet de paramétrer l'expression, comme le nombre dans l'exemple suivant, mais qui sera au singulier par défaut. L'utilisation d'une fonction fléchée (pommeFF) simplifie la notation.

AS an alternative to clone(), a function can be assigned to a variable. Each call to this function creates a new expression. This also allows parameterizing the expression, e.g. the number in the following example that is singular by default. The use of an arrow function (appleAF) simplifies the notation.

.add(element,position)

Ajout d'un nouveau syntagme element comme enfant à un syntagme existant. Le paramètre entier position est facultatif et spécifie la position (à partir de 0) dans le syntagme. Par défaut, l'élément est ajouté à la fin.

Add a new phrase element as a child of an existing phrase. The second optional parameter position is an integer that specifies its position (counting from 0). By default, the element is added as the last child.

.toSource()

Cette fonction retourne une version chaîne d'une expression jsRealB, ceci peut être utile pour la mise au point d'une expression complexe. En passant 0 comme paramètre à ce fonction, on obtient une expression indentée qui fait ressortir la structure de l'expression.

This function returns a string version of a jsRealB expression, this can be useful for debugging complex expressions. But giving 0 as parameter of this function, the expression is indented to show the underlying structure.

getLanguage()

Cette fonction retourne le langage courant de réalisation: "fr" pour le français et "en" pour l'anglais.

This function returns the current realization language: "fr" for French and "en" for English.

loadEn(trace), loadFr(trace)

Ces fonctions indiquent la langue à utiliser pour les prochaines réalisations. Il est important d'en appeler au moins une avant de débuter la réalisation d'une phrase. Le paramètre (false by default) est le suivant:

These functions sets the current realization language; one of them should be called before starting the realization process. Its parameter, (false by default) is :

Chargement dans une page web

Loading in a web page

Il suffit d'ajouter le script jsRealB.js à la liste des scripts de la page. Ceci intègre déjà deux lexiques de base: français (3 700 entrées) et anglais (5 200 entrées). Comme indiqué à la section Extension du vocabulaire, il est facile d'ajouter de nouvelles entrées ou même de remplacer complètement les dictionnaires par défaut.

It is only a matter of adding the script jsRealB.js to the scripts used by the web page. This includes two basic lexicons: English (5 200 entries) and French (3 700 entries). As shown below in the Vocabulary extension section, it is possible to add new entries to the lexicon or to change it completely.

Il est possible d'appeler ces fonctions aussi souvent que nécessaire pour changer le langage de réalisation courant. Ces fonctions retournent le nouveau dictionnaire chargé.
These functions can be called as often as necessary to change the current language. Each call returns the last loaded dictionary.

Idéalement, vous installerez votre propre version de jsRealB à partir des sources du GitHub et vous la référencerez depuis l'élément script. Mais vous pouvez aussi télécharger une version déjà minifiée à partir de ce répertoire.

Ideally you should install your own version of jsRealB from the GitHub sources and you will refer to it using a script element. But you can also get minified versions from this directory.

Des exemples d'intégration dans une page web peuvent être trouvés à la section Démonstrations de cette page

Examples of web page integration can be found at the Demonstrations section of this page

Module Node.js

Node.js Module

Les versions de jsRealB décrites à la section précédente peuvent aussi être utilisées avec node.js en utilisant une instruction de la forme jsRealB=require("...")

The jsRealB versions can also be used with node.js with an instruction like jsRealB=require("...")

Un exemple simple d'utilisation du module Node.js est ce filtre Unix qui accepte une expression jsRealB sur une seule ligne et retourne sa réalisation en anglais.

A simple example of the use of the Node.js module is this Unix filter which transforms a jsRealB expression on a single line and returns the corresponding English realization.

Trucs pratiques:

Useful tricks:

Gestion des lexiques

Lexicon Management

jsRealB intègre déjà deux lexiques de base: français (3 700 entrées) et anglais (5 200 entrées) qu'il est possible de consulter et de modifier à l'aide des fonctions suivantes. Lorsque lang ("en" ou "fr") est spécifié, la fonction s'applique au lexique de cette langue, sinon au lexique courant, celui du dernier appel à loadEn() ou loadFr().

jsRealB has already two basic lexicons: French (3 700 entries) and English (5 200 entries) that can be queried and modified with the following functions. When lang ("en" or "fr") is specified, the function is applied to the lexicon of this language, otherwise it applies to the current lexicon, the one of the last call to loadEn() o loadFr().

addtoLexicon(lemma[,newInfos][,lang])

lemma est l'entrée de base et newInfos est l'information morphologique selon le format interne à jsRealB: un objet indiquant le ou les catégories possibles et pour chaque catégorie, des propriétés et la table de déclinaison ou conjugaison correspondantes. Par exemple, addLexicon("jsRealB",{"N":{"g":"m", "pe":3, "tab": ["nI"]}) ajoutera le mot jsRealB comme nom masculin invariable au lexique courant. Cette fonction peut aussi être appelée avec un seul paramètre qui est un objet dont la clé est le lemme. L'exemple précédent peut donc s'écrire: addToLexicon({"tsunami":{"N":{"tab":["n1"]}}}). Si le lemme et la catégorie existent déjà dans le lexique, alors l'entrée pour cette catégorie est remplacée par newInfos.

Plus d'information (en anglais) sur le format des lexiques

Pour déterminer les informations à ajouter, le plus simple est de copier les informations d'un mot du lexique qui se conjugue ou se décline de la même façon. L'IDE de jsRealB permet de consulter les informations du lexique.

Pour enlever une entrée d'un lexique, il de mettre newInfos à null.

lemma is the basic form and newInfos is the morphologic information according to the internal jsRealB format: an object indicating one or many possible categories. For each category, properties and declension or conjugation are given. For example, addLexicon("jsRealB",{"N":{"g":"m", "pe":3, "tab": ["nI"]}) will add the jsRealB as a masculine invariable word. This function can also be called with a single parameter: an object whose key is the lemma. The previous example could also have been written: addToLexicon({"tsunami":{"N":{"tab":["n1"]}}}). If the lemma and category are already present in the lexicon, then the category of this entry is replaced by newInfos.

More information about the lexicon format

In order to find the informations to add, the simplest way is to copy the lexicon information for a similar word already in the lexicon. The jsRealB IDE provides access to the lexicon information.

To remove an entry, set newInfos to null.

getLemma(lemma[,lang])

Retourner les informations du lexique correspondant à lemma.

Return lexicon information to lemma.

updateLexicon(newLexicon[,lang])

Fusionner les entrées de newLexicon avec le lexique spécifié. Ceci ajoutera les nouvelles entrées et remplacera les entrées existantes par celles du nouveau lexique. La fusion est effectuée au niveau des entrées, mais non des catégories.

Merge the entries of newLexicon with the specified lexicon. This adds the new entries and replaces the existing entries by the ones of the new lexicon. Merging is done at the entry level, not at the category level.

getLanguage()

Retourne le langage de réalisation courant.

Returns the current realization language.

getLexicon()

Retourne le lexique courant.

Returns the current lexicon.

Sélection de variantes

Variant selection

La fonction oneOf(e1,e2,...)ei est est une valeur, choisit un ei au hasard. En jsRealB, ces éléments sont souvent des constructeurs correspondant à des structures de phrases différentes. Si e1 est une liste alors la sélection est faite dans cette liste, en ignorant les autres paramètres.

Pour éviter que tous les éléments soient évalués avant la sélection, il suffit de fonctionaliser l'expression en une fonction sans paramètre en la préfixant par ()=>, ce qui en fait une fonction fléchée. Une fois l'élément choisi, oneOf vérifie si la valeur est une fonction et si c'est le cas, il retourne le résultat de l'appel. Par exemple, ofOne(()=>N("amour"),()=>N("amitié")) permet de choisir entre les deux noms sans évaluer les deux constructeurs. Dans ce cas, très simple, il aurait été aussi possible d'écrire N(oneOf("amour","amitié")).

The function oneOf(e1,e2,...) where ei is a value, selects randomly a ei. In jsRealB, these elements are often constructors corresponding to different phrase structures. If e1 is a list, the selection is performed within this list, ignoring other parameters.

To avoid the evaluation of all elements before the selection, it is possible to functionalize a expression into a function with no formal parameter by prefixing it with ()=> which makes it an arrow function. Once the element is selected, oneOf checks if the value is a function and, if it is so, it returns the value of the called function. For exemple, oneOf(()=>V("love"),()=>V("like")) allows choosing between the two verbs without evaluating both constructors. In this simplistic case, this could have also been written as V(oneOf("love","like")).

Traitements en JSON

JSON processing

Pour faciliter l'utilisation de jsRealB en sortie d'un système externe. Il est possible d'utiliser un format d'entrée JSON décrit dans ce document (en anglais). Il est également possible d"obtenir une expression JSON correspondant à une expression jsRealB.

To simplify the use of jsRealB as output of an external system, a JSON input format has been defined. It is described in this document.. It is also possible to obtain the JSON expression corresponding to a given jsRealB expression.

Informations complémentaires

More Information