/* Kit de Localisation - DMS - August 99 - by Sebastien DENEUX */


Le kit de localisation permet l'affichage de messages textes dans diffrentes langues.
Les messages sont stocks dans des fichiers de ressources.

Pour chaque module DMS, un fichier de ressource par langue doit tre cr.
Les fichiers de ressources ainsi cr doivent se trouver dans un sous rpertoire /lang du module.
Les fichiers respecteront la syntaxe suivante :
 - le nom du fichier reprend le nom du module (nom du fichier .dmc sans son extension)
 - une premire premire extension indique le nom de la langue du fichier de ressource 
    (langue en Anglais,  exemple : .english, .french,...)
 - une seconde extension, .lang, permet d'identifier les fichiers de ressources.

exemple de nom de fichier de ressources : test.french.lang

Chaque ligne du fichier de ressource correspond  une rfrence et  la traduction du message correspondant
dans la langue spcifie dans le nom du fichier.

Le kit de localisation permet aussi de grer des messages avec des paramtres.

Le tlchargement des fichiers du serveur vers les clients est automatique.

Le client rcupre les fichiers dans la langue de son SCOL Engine.

Lorsqu'il change de langue, les fichiers correspondant  la nouvelle langue sont tlchargs automatiquement.

Chez le client, les fichiers de ressources sont stocks sous la forme nomDuModule.lang directement dans le rpertoire du module.


* SYNTAXE DU FICHIER DE RESSOURES :

Si vous voulez insrez des commentaires, commencez la ligne par #.
Par dfaut les rfrences sont accessibles  la fois ct client et ct serveur. Pour rendre les rfrences accessibles
uniquement ct client, commencer le nom de la rfrence par une toile. (n'utilisez pas l'toile lors de l'appel de la fonction
de localisation, celle ci est automatiquement supprim lors du chargement des fichier en mmoire).

Au sein d'un message, on utilise \n pour le retour chariot.
Les espaces en dbut de message, en fin de message ou deux ou plus espaces qui se suivent ne seront pas pris en compte. 
Il est toutefois possible d'utiliser le \[espace] pour y remdier mais il est prfrable d'ajouter les espaces directement
dans le code des programmes, ce qui vite d'ventuels oublis lors de la traduction des fichiers de ressources.

Les paramtres sont dfinis  l'aide de la syntaxe <#no:texte>
 - no est un entier reprsentant le no du paramtre (qui commence  0)
 - texte une chaine de caractre permettant de prciser la nature du paramtre
(cette chaine ne doit contenir aucun espace : utiliser le _ par exemple comme sparateur)
Il est ainsi possible d'insrer un paramtre plusieurs fois. Les paramtres peuvent tre insrs dans n'importe quel ordre.



* NOTE SUR LE CHOIX DES REFERENCES:
	Le fichier de ressource est charg en mmoire dans une hashtable de 256 cases. La fonction de hachage 
remplit le tableau en fonction de la somme des deux premiers caractres ASCII de la rfrence modulo 256.
Il ne faut donc pas toujours faire commencer les rfrences par les mmes caractres.

* API SERVEUR :

fun _loc [DMI S [S r1]] S

->  permet de localiser le serveur dans la langue du scol engine serveur.
    retourne la localisation de la reference (2me paramtre de la fonction) avec des paramtres insrs (3me paramtre de la fonction).


fun _locCli [DMI CLIENT S [S r1]] S

-> permet d'envoyer au client une rfrence localise dans sa langue 
   (langue du scol engine du client si disponible, sinon langue du scol engine du serveur)
   retourne la localisation de la reference (3me paramtre de la fonction) avec des paramtres insrs (4me paramtre de la fonction).
   si la rference n'existe pas dans la langue du client, retrourne la rfrence traduite dans la langue du serveur.


fun _locCliEx [DMI S S [S r1]] S

-> identique _locCli, mais on spcifie la langue du client 
   par exemple, pour envoyer des email  un client dans sa langue alors qu'il n'est pas connect,
   on spcifie la langue du client (2me paramtre de la fonction) en la rcuprant dans une base de donnes serveur.
   retourne la localisation de la reference (3me paramtre de la fonction) avec des paramtres insrs (4me paramtre de la fonction).
   si la rference n'existe pas dans la langue du client, retrourne la rfrence traduite dans la langue du serveur.

fun _locAddRef [DMI S S S] I

-> permet d'ajouter dynamiquement une refrence  localiser (3me paramtre de la fonction) avec son contenu (4me paramtre) pour
   une langue donne (2me paramtre)
   retourne 1 si ajout effectu, 0 sinon.

fun _locDelRef [DMI S S] I

-> permet de supprimer une rfrence (3me paramtre de la fonction) dynamiquement pour une langue donne (2me paramtre)
  retourne 1 si suppression effectu, 0 sinon.

fun _DMSreinitLoc [DMI] I

-> recharge dynamiquement les fichiers de localisation sur le serveur et chez les clients connects.

* API CLIENT : 

fun _loc [DMI S [S r1]] S

->  permet de localiser le client dans la langue du scol engine client (langue du scol engine serveur si la langue du client est inexistante)
    retourne la localisation de la reference (2me paramtre de la fonction) avec des paramtres insrs (3me paramtre de la fonction).



En cas d'erreur, les fonctions renvoient :
	- "!!ERR_REF!!" quand la rfrence est inexistante
	- "!!ERR_PARAM!!" quand un paramtre est manquant


* NOTE SUR LES PARAMETRES : les paramtres peuvent eux-mme tre des rfrences  traduire.


* API EDITEUR

/*A APPELER PAR LE TEMPLATEEDIT !!!*/
fun iniLocEditor [editorPath S className S] I

-> initialisation de la table de localisation.
   les fichiers de langues doivent se trouver dans le sous rpertoire /editorLang du rpertoire editorPath (editorPath ne doit pas finir par un /), et porter pour nom le nom
   de la classe (className) suivi du nom de la langue. Ex : test.french.lang

fun _locEditor [S [S r1]] S

->  permet de localiser l'editeur dans la langue du scol engine serveur.
    retourne la localisation de la reference (2me paramtre de la fonction) avec des paramtres insrs (3me paramtre de la fonction).
