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


Le kit de localisation permet l'affichage de messages textes dans différentes langues.
Les messages sont stockés 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 répertoire /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 première première 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 référence et à la traduction du message correspondant
dans la langue spécifiée dans le nom du fichier.

Le kit de localisation permet aussi de gérer des messages avec des paramètres.

Le téléchargement des fichiers du serveur vers les clients est automatique.

Le client récupère les fichiers dans la langue de son SCOL Engine.

Lorsqu'il change de langue, les fichiers correspondant à la nouvelle langue sont téléchargés automatiquement.

Chez le client, les fichiers de ressources sont stockés sous la forme nomDuModule.lang directement dans le répertoire du module.


* SYNTAXE DU FICHIER DE RESSOURES :

Si vous voulez insérez des commentaires, commencez la ligne par #.
Par défaut les références sont accessibles à la fois côté client et côté serveur. Pour rendre les références accessibles
uniquement côté client, commencer le nom de la référence 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 mémoire).

Au sein d'un message, on utilise \n pour le retour chariot.
Les espaces en début 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 remédier mais il est préférable 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 paramètres sont définis à l'aide de la syntaxe <#no:texte>
 - no est un entier représentant le no du paramètre (qui commence à 0)
 - texte une chaine de caractère permettant de préciser la nature du paramètre
(cette chaine ne doit contenir aucun espace : utiliser le _ par exemple comme séparateur)
Il est ainsi possible d'insérer un paramètre plusieurs fois. Les paramètres peuvent être insérés dans n'importe quel ordre.



* NOTE SUR LE CHOIX DES REFERENCES:
	Le fichier de ressource est chargé en mémoire dans une hashtable de 256 cases. La fonction de hachage 
remplit le tableau en fonction de la somme des deux premiers caractères ASCII de la référence modulo 256.
Il ne faut donc pas toujours faire commencer les références par les mêmes caractères.

* 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 (2ème paramètre de la fonction) avec des paramètres insérés (3ème paramètre de la fonction).


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

-> permet d'envoyer au client une référence localisée dans sa langue 
   (langue du scol engine du client si disponible, sinon langue du scol engine du serveur)
   retourne la localisation de la reference (3ème paramètre de la fonction) avec des paramètres insérés (4ème paramètre de la fonction).
   si la réference n'existe pas dans la langue du client, retrourne la référence traduite dans la langue du serveur.


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

-> identique _locCli, mais on spécifie la langue du client 
   par exemple, pour envoyer des email à un client dans sa langue alors qu'il n'est pas connecté,
   on spécifie la langue du client (2ème paramètre de la fonction) en la récupérant dans une base de données serveur.
   retourne la localisation de la reference (3ème paramètre de la fonction) avec des paramètres insérés (4ème paramètre de la fonction).
   si la réference n'existe pas dans la langue du client, retrourne la référence traduite dans la langue du serveur.

fun _locAddRef [DMI S S S] I

-> permet d'ajouter dynamiquement une reférence à localiser (3ème paramètre de la fonction) avec son contenu (4ème paramètre) pour
   une langue donnée (2ème paramètre)
   retourne 1 si ajout effectué, 0 sinon.

fun _locDelRef [DMI S S] I

-> permet de supprimer une référence (3ème paramètre de la fonction) dynamiquement pour une langue donnée (2ème paramètre)
  retourne 1 si suppression effectué, 0 sinon.

fun _DMSreinitLoc [DMI] I

-> recharge dynamiquement les fichiers de localisation sur le serveur et chez les clients connectés.

* 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 (2ème paramètre de la fonction) avec des paramètres insérés (3ème paramètre de la fonction).



En cas d'erreur, les fonctions renvoient :
	- "!!ERR_REF!!" quand la référence est inexistante
	- "!!ERR_PARAM!!" quand un paramétre est manquant


* NOTE SUR LES PARAMETRES : les paramètres peuvent eux-même être des références à 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 répertoire /editorLang du répertoire 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 (2ème paramètre de la fonction) avec des paramètres insérés (3ème paramètre de la fonction).