NIH ou Aide interactive multi-langues

(Système d'aide interactive permettant une cohabitation harmonieuse entres applications anglophones et applications traduites) La version courante est 0.2
Auteur: Benoît GILON

Présentation du contexte

Le système d'internationalisation d'applications sous RISC OS est sans doute l'un des plus flexibles qui soit sur notre planète.
Pour les personnes souhaitant développer des applications multi-langages, elles utilisent alors les outils standard de développement, avec un fichier par type de ressource et langue supportée (ou un répertoire par langue supportée).
Les applications écrites en BASIC peuvent tirer parti de la perle d'astuce au sein du code ResFind (écrit par Olaf krumnow et Herbert zur Hedden du German Archimedes Group).
Les programmes écrits en C peuvent tirer profit du programme SetRes écrit par votre serviteur pour toutes les applications Toolbox (ou bien se référer à l'article Local pour des applications utilisant la RISCOSlib).
L'aide interactive permet aux applications clientes, lorsqu'elles retournent des messages à afficher dans la fenêtre de l'application !Help, de spécifier au sein du texte des tokens qui sont ensuite traduits par l'application !Help en messages en clair après consultation dans un dictionnaire.
Cela permet de raccourcir les données échangées (et donc permet de faire tenir la totalité du texte dans un unique message Wimp).
Chaque token est préfixé au sein du texte transmis par un caractère d'échappement qui est la barre inverse '\' et son code se trouve représenté par un unique caractère dont le code est supérieur à l'espace.
Vous pouvez vous rendre compte de ce mécanisme en consultant les fichiers dont le chemin d'accès correspond au pattern 'Resources:$.Resources.*.Messages'. Allez dans les sous répertoires correspondant à toute application tournant sous le bureau.
Malheureusement, le bénéfice de cette facilité ne pouvait s'effectuer que si toutes les applications utilisent la même langue. A priori, cela doit être l'Anglais parce que:

vous n'avez pas encore traduit toutes les applications de votre bureau RISC OS;
vous comptez encore pouvoir exécuter des applications anglophones nouvellement atterries ou sur le point d'atterrir sur votre disque dur.

Si vous vous contentez de traduire les définitions des tokens dans le fichier Messages local à l'application !Help. Vous vous retrouverez avec des messages "franglais" du plus beau style du type:
"Cliquez SELECT pour merge the paths.". La partie italique soulignée et de couleur rouge provient de la traduction du token '\S' effectuée par l'application !Help. et le reste du message a comme origine l'application cliente, anglophone nouvellement installée.
Ma nature maniaque (disons perfectionniste ;-) me sussure que cela ne doit pas se produire sur un bureau d'une machine dont je vante par ailleurs les qualités d'ergonomie auprès de mes collègues de bureau.
Donc et jusqu'à maintenant, toutes les définitions destinées à l'aide interactive présentes dans les fichiers de ressources pour une langue supportée autre que l'Anglais ne comportent aucun token.
Ceci implique:

Encore plus de frappes au clavier lors du développement pour rentrer le texte en clair;
Mémoire consommée par l'application plus importante;
Performance moindre (?);

Fonctionnalité des outils proposés

Ce qui est proposé dans le présent article est une méthode permettant la gestion par une application !Help patchée de deux jeux de tokens séparés:

Les anciens tokens sont inchangés dans leur définition et sont destinés aux applications anglophones;
Les nouveaux tokens permettent une traduction suivant la langue pratiquée par l'utilisateur si ce dernier ne parle pas l'Anglais.

Bien entendu, les nouvelles applications localisées utiliseront dans leur fichier de ressources le nouveau jeu de tokens. La sélection du nouveau jeu s'effecturea en dédoublant le préfixe '\'. Ainsi, la donnée "\\Srassembler les chemins." transitant vers l'application !Help provoquera l'affichage du message "Cliquez SELECT pour rassembler les chemins." dans la fenêtre !Help.
Cela implique:

Une modification de l'application !Help pour traiter deux jeux de tokens;
Une modification de l'application !Help pour bien positionner la variable Help$Path afin que le fichier Messages cherché soit celui correspondant à la langue pratiquée.
Une modification des applications clientes pour fournir des fichiers de ressources différentiés suivant la présence ou l'absence de la nouvelle application d'aide interactive.

Patch de l'application !Help (fichier !RunImage)

La procédure chargée de la traduction des données incluses dans le message provenant de l'application cliente est la procédure "e" dont le code suivant est une partie:

DEFPROCe:LOCALx%,T%,M%,A%,p%,m%,N%,I%,y%,oa%: \
SYS39,a%+20,n%,512+(1<<31)TOp%,,A%:A%+=n%:?A%=13:p%?-1=13:t$=$(a%+20):IFt$=c$ENDPROC
c$=t$:y%=J%:FORx%=n%TOA%:?y%=?x%:IF?x%<>ASC("\")THEN
y%+=1
ELSE:x%+=1:IF?x%=ASC("\")THEN
y%+=1
ELSE:$(y%)=FNa("T"+CHR$(?x%)):IF?y%=ASC("T")AND?(y%+1)=?x%ANDLEN($(y%))=2THEN?y%=ASC("\")
y%+=LEN($(y%))
ENDIF
ENDIF

Le code suivant est la version patchée: une variable locale z$ supplémentaire contient la première lettre du token à chercher dans le fichier Messages local.

DEF PROCe:LOCAL x%,T%,M%,A%,p%,m%,N%,I%,y%,oa%,z$: \
SYS39,a%+20,n%,512+(1<<31)TOp%,,A%:A%+=n%:?A%=13:p%?-1=13:t$=$(a%+20):IF t$=c$ENDPROC
c$=t$:y%=J%:FOR x%=n%TOA%:?y%=?x%:IF?x%<>ASC("\")THEN
y%+=1
ELSE:x%+=1:IF?x%=ASC("\")THENx%+=1:z$="U"ELSEz$="T"
$(y%)=FNa(z$+CHR$(?x%)):IF?y%=ASC(z$)AND?(y%+1)=?x%ANDLEN($(y%))=2THEN?y%=ASC("\")
y%+=LEN($(y%))
ENDIF

Mise en place de la variable Help$Path

Cela se fait habituellement au sein du fichier !Run de l'application !Help. Comme !Help est une application BASIC, il est naturel d'adopter la solution de l'utilisation de ResFind.
Voici le fichier d'origine de !Run situé dans Resources:$.Apps.!Help:

| > !Run
| Check for the required amount of memory first
WimpSlot -min 32K -max 32K
| Having succeeded there, do not start up if
| Help is already running.
If "<Help$Dir>"<>"" Then Error Help is already running
| Then start the application
Set Help$Dir <Obey$Dir>
Set Help$Path <Obey$Dir>.,Resources:$.Resources.Help.
Run Help:!RunLink

Et maintenant le nouveau fichier (une version modifiée existe et se trouve dans l'archive si l'application doit être accessible à travers l'icône Apps de la barre d'icônes; utilisation de la commande RISC OS AddAp).

| > !Run
| Check for the required amount of memory first
WimpSlot -min 32K -max 32K
| Having succeeded there, do not start up if Help is already running.
If "<Help$Dir>"<>"" Then Error Help is already running
| Then start the application
Run <Obey$Dir>.Resources.ResFind
Unset HelpRes$Path
Unset Help$Dir
If "<HelpRes$Dir>"="<Obey$Dir>" Then /Resources:$.Apps.!Help
Set Help$Path <HelpRes$Dir>.,Resources:$.Resources.Help.
Unset HelpRes$Dir
Set Help$Dir Resources:$.Apps.!Help
Run <Obey$Dir>.!RunImage

Modification des applications clientes

Applications utilisant la Toolbox

Nous nous appliquerons à transformer des applications clientes utilisant le programme SetRes maintes fois utilisées dans les applications que j'ai écrites.
Pour mémoire, SetRes positionne une variable d'environnement <AppNameR$Dir> en fonction d'un paramètre fourni en entrée "<AppName>" et de la valeur du country couramment positionné.
Pour toute langue supportée, nous aurons deux fichiers res (en présumant que tous les textes de messages à destination de l'aide interactive se trouvent dans ce fichier).

Un fichier se trouvant dans <AppNameR$Dir> pour les messages n'utilisant pas les tokens;
Un fichier se trouvant dans <AppNameR$Dir>.nhelp pour les messages utilisant les tokens.

Le problème avec l'API toolbox_initialize est qu'elle requiert que le chemin où trouver les fichiers res et Messages soit unique et ne semble pas accepter de désignation de pseudo FS pour contourner ce point.
Pour le moment, nous dupliquerons le fichier Messages dans chaque répertoire. Peut être une solution plus économe verra le jour dans quelques temps. Le choix de sélectionner un fichier ou un autre se fera sur les critères suivants:

La variable Help$Path existe-t-elle?
Le système de fichiers supportant le fichier Help:!RunImage est-il ResourcesFS?
La variable Help$Dir existe-t-elle? Si oui cela implique que l'application !Help est active.

Le nouveau fichier nhelp.res sera choisi si toutes les conditions suivantes sont respectées:

La variable Help$Path existe;
Le fichier Help:!RunImage n'est pas supporté par RessourceFS (voir à ce propos le programme BASIC Ressources:$.Resources.Help.RunLink);
Le country couramment fixé au sein du Help$Path est celui sélectionné par l'application.
Le répertoire <AppNameR$Dir>.nhelp existe et contient un jeu de fichiers res/Messages;

Le programme qui assure ces vérifications est un petit programme BASIC (s'appuyant sur du code tiré de ResFind) et qui est joint à l'archive.
Ce programme part de la valeur actuelle de la variable <AppName>R$Dir et va l'enrichir en fonction des conclusions sur les fait exposé ci-dessus.

Applications en BASIC ou utilisant la RISCOSLib

Le mécanisme de mise à jour des applications BASIC s'effectue par utilisation de deux petits modules écrits eux-même en BASIC.

ResFind par Olaf Krumnow et Herbert zur Hedden du German Archimedes Group que vous connaissez déjà;
MResFind qui fait aussi partie de l'archive. Prend en compte la valeur prise par la variable système AppNameRes$Path telle que positionnée suite à l'appel au module précédent, et préfixe cette valeur (ou la laisse inchangée) avec la désignation du répertoire adhoc pour tenir compte d'un nouveau fichier "Messages" conforme au standard NIH.

La variable système sera actualisée si toutes les assertions suivantes se révèlent vraies:

La variable d'environnement Help$Path existe;
Le fichier Help:!RunImage n'est pas supporté par le système de fichiers ResourceFS (cf voir le petit programme BASIC Resources:$.Resources.Help.RunLink);
La désignation du pays apparaissant éventuellement dans la valeur prise par la variable Help$path est la même que celle du pays sélectionné pour l'application;
Le répertoire <AppNameRes$Dir>.nhelp existe;

Le changement de valeur de la variable s'opérant, un essai d'accéder au fichier par la désignation AppNameRes:Messages accédera au fichier <AppNameRes$Dir>.nhelp.Messages et non plus <AppNameRes$Dir>.Messages.

Parmi les applications de ce type qui ont été converties afin de les rendre compatibles avec NIH, on peut citer la dernière version de !Player de ESP ainsi que le résultat de mon initiative de localisation de !StrongED (4.62) que vous pourrez trouver également sur ce site.

Une application "Helper": !NIHTool

Celle-ci est un outil vous aidant dans les tâches suivantes:

Convertir vos "vieux" fichiers Messages (ne contenant pas ou peu de tokens en leur sein) en un format compatible avec NIH (tokens préfixés par '\\');
A partir d'un fichier au nouveau format, reconstituer un fichier la version d'origine: cela permet de n'avoir qu'une seule référence;
Travailler avec les fichiers Messages d'applicaions non encore localisées afin de détecter les endroits ou un remplacement de token est encore possible et donc de réduire encore sa taille de quelques octets.

Typiquement, le processus peut être résumé: il considère trois entrées (dont deux sont des fichiers, et la dernière étant un jeu d'options positionnées par l'utilisateur de l'outil).

Un fichier "dictionnaire" qui contient un ou plusieurs jeux de définitions (association entre tokens et "textes en clair");
Un fichier source qui contient les données à convertir d'une certaine façon.

Ces deux paramètres (et d'autres) peuvent être entrés avec l'aide de la boîte de dialogue ci-dessous:
NIHTool setup window

La désignation du fichier source doit être entrée au sein de l'icône libellée 'Source' (des op[eration de glisser/déposer sont aussi possibles);
La désignation du fichier "dictionnaire" peut aussi être modifié de la même manière;
Le bouton d'option "Throwback" spécifie que l'utilisateur souhaite corriger les erreurs potentielles par un lien avec un éditeur de texte;
Le bouton d'option "Expand mode" spécifie le sens de la conversion qui devra avoir lieu sur le fichier source:
- pour convertir des tokens en "texte en clair", laisser cette case cochée;
- pour convertir du "texte en clair" en tokens, cette case doit être non cochée.

Les options plus ésotériques peuvent être activées par utilsation du menu surgissant (popup) ci-dessous:

L'entrée "Dictionary character" spécifie quel caractère est utilisé comme référence dans le dictionnaire pour le processus de conversion qui va suivre. Par défaut, c'est 'U', ce qui signifie que le jeu de tokens correspondant à des messages localisés est utilisé (cf. extrait du fichier Help:Messages dans mon RISC PC lorsque NIH est installé: US:Cliquez SELECT pour ). Cependant, si vous voulez jouer avec les fichiers de message originaux (non traduits), vous pouvez spécifier la lettre 'T' pour cette option (cf autre extrait du fichier Help:Messages: TS:Click SELECT to ).
Typiquement, le processus de conversion ignore les segments du texte source annoncés par le caractère '#' (commentaire). Cependant, certaines applications (dont !StrongED) utilisent des fichiers Message où la présence de ce caractère sert un autre but que marquer un début de commentaire. C'est la raison d'être de l'option 'Process commented segments' qui donne instruction à l'outil de considérer le caractère '#' comme tout autre caractère.
Par défaut, la séquence d'échappement est définie comme '\\', ce qui est adéquat lorsque l'on travaille avec des fichiers Messages au standard NIH, toutefois, vous pouvez avoir besoin de travailler avec les codes d'échappement d'origine ('\') sur les fichiers Message d'origine juste pour vérifier que vous bénéficier pleinement du mécanisme de tokenisation offert par le dictionnaire de l'application IH (en termes d'espace disque comme d'occupation en mén£moire).
De plus, une option ('-p') existe pour spécifier les lignes qui seront l'objet de la conversion et donc celles qui y échapperont. Si l'option inclut un paramètre chaine au format GSTrans, alors uniquement les lignes commencant par cette chaine seront objet de la conversion et les autes resteront inchangées. Ainsi...
NIHTool -p Hicon ... convertira toutes les lignes du fichier source commencant par la chaine Hicon.

Conclusion

Après ces quelques aménagements, vous aurez un système:

avec des applications parlant complètement Anglais si elles sont anglophones;
avec des applications parlant complètement la langue de l'utilisateur pour les applications proprement configurées;
respectant l'indépendance entre le système d'aide interactive et l'application cliente;
permettant un gain de place en mémoire pour de grosses applications muli-langues si l'utilisateur a choisi d'installer la version patchée de l'aide interactive.

A ceux qui s'emploient à traduire des briques du système RISC OS, j'espère que la lecture de cet article les aura aidé. N'hésitez pas à me contacter pour toute demande de renseignements complémentaires.

Toute remarque constructive est la bienvenue.

La traduction des messages de l'application !Help elle même ainsi que des définitions des tokens (texte en clair) n'est pas terminée à ce jour; (une version complète verra le jour sur ce site).
La première application qui va adopter ce dispositif sera mon carnet d'addresses sous RISC OS, suivie de toute nouvelle application que je pourrais écrire.