ORM_AddTranslation
Insère ou met à jour la traduction d'un libellé métier dans le référentiel multilingue cshx2_traductions. Comportement upsert : si l'enregistrement existe déjà pour la combinaison (table, colonne, tuple, langue, genre), il est mis à jour ; sinon il est créé.
📋 Description
ORM_AddTranslation est la procédure d'écriture du référentiel multilingue. Elle reçoit un texte traduit et les coordonnées de la donnée source (table, colonne, identifiant du tuple, langue cible, type grammatical, genre), puis enregistre cette traduction dans la table système cshx2_traductions.
L'appelant n'a pas à se préoccuper de savoir si la traduction existe déjà ou non — la procédure se charge de l'insertion ou de la mise à jour selon le cas, en une seule opération idempotente.
1. Enregistrer la traduction d'un libellé métier dans une langue cible. Cas typique : on a une donnée saisie dans la langue principale (par exemple le libellé d'un article en français) et on veut enregistrer sa version traduite (anglais, allemand, etc.) dans le référentiel multilingue.
2. Mettre à jour une traduction existante. Si la traduction pour la combinaison (table, colonne, tuple, langue, genre) existe déjà, elle est remplacée par la nouvelle valeur. Le code appelant n'a pas à se soucier de savoir si l'opération est un INSERT ou un UPDATE.
3. Initialiser un référentiel de traductions par traitement automatique. Boucle d'import depuis un fichier de traductions externe, ou peuplement initial après création d'un nouvel enregistrement métier.
La procédure recherche d'abord une traduction existante pour la combinaison (table, colonne, tuple, langue, genre). Si aucune n'existe, elle l'insère. Si une seule existe, elle la met à jour. Si plusieurs existent (anomalie d'intégrité), elle remonte l'erreur ERR_TRANS_DATABASE_INTEGRITY.
🔑 Signature
LOCAL sTranslation est une chaîne,
LOCAL sSQLTable est une chaîne,
LOCAL sSQLField est une chaîne,
LOCAL nRowID est un entier,
LOCAL nLanguageID est un entier,
LOCAL nWordType est un entier,
LOCAL nWordGender est un entier = 0
) : (booléen, entier, chaîne)
| Élément | Valeur |
|---|---|
| Visibilité | PUBLIQUE |
Paramètres
| Paramètre | Type | Défaut | Rôle |
|---|---|---|---|
sTranslation | chaîne | — | Texte traduit à enregistrer dans la langue cible. |
sSQLTable | chaîne | — | Nom de la table SQL contenant la donnée source à traduire (ex : "cshx2_articles"). |
sSQLField | chaîne | — | Nom de la colonne SQL contenant la donnée source à traduire (ex : "DESIGNATION"). |
nRowID | entier | — | Clé primaire de l'enregistrement source dont on enregistre la traduction. |
nLanguageID | entier | — | Identifiant de la langue cible (référentiel cshx2_langues). |
nWordType | entier | — | Type grammatical du mot. |
nWordGender | entier | 0 | Genre du mot — voir §03 pour les valeurs (0 neutre, 1 masculin, 2 féminin). |
Valeur de retour
| Élément | Type | Description |
|---|---|---|
bProcessing | booléen | Vrai si l'opération a réussi (insert ou update), Faux en cas d'échec. |
nErrorCode | entier | Code d'erreur négatif en cas d'échec, 0 sinon. |
sErrorMessage | chaîne | Message d'erreur lisible en cas d'échec. |
🧭 Clé d'unicité de la traduction
Une traduction dans cshx2_traductions est identifiée de manière unique par la combinaison de cinq valeurs. Cette combinaison détermine si l'opération est un INSERT (aucune ligne n'existe) ou un UPDATE (une ligne existe déjà) :
| Composante | Source |
|---|---|
| Table SQL | Paramètre sSQLTable |
| Colonne SQL | Paramètre sSQLField |
| Clé primaire du tuple | Paramètre nRowID |
| Langue cible | Paramètre nLanguageID |
| Genre grammatical | Paramètre nWordGender |
Les paramètres sTranslation (texte traduit) et nWordType (type grammatical) ne participent pas à la clé d'unicité — ce sont des attributs portés par la traduction. Plusieurs appels successifs avec la même clé mais des textes différents écrasent donc toujours la même ligne.
Valeurs du paramètre nWordGender
| Valeur | Genre |
|---|---|
0 (défaut) | Neutre |
1 | Masculin |
2 | Féminin |
Le genre fait partie de la clé d'unicité : il est ainsi possible d'enregistrer deux traductions distinctes pour le même libellé selon le genre attendu côté affichage (par exemple un adjectif qui s'accorde différemment).
⚠️ Gestion des erreurs
| Constante | Condition |
|---|---|
ERR_TRANS_DATABASE_INTEGRITY | Plusieurs lignes existent déjà dans cshx2_traductions pour la même combinaison (table, colonne, tuple, langue, genre). Anomalie d'intégrité — la procédure refuse l'opération pour ne pas masquer le problème. |
Hors ce cas spécifique, la procédure remonte également les codes d'erreur génériques de la couche de persistance (échecs de chargement, contraintes d'intégrité SQL, conflits de verrouillage…). Voir ORM_Transactions pour les erreurs liées aux transactions.
💡 Exemples
Mode 1 — enregistrer une traduction (INSERT ou UPDATE transparent)
Cas d'usage : l'utilisateur saisit la traduction anglaise du libellé d'un article et clique sur « Enregistrer ».
"Quick-disconnect coupling", // texte traduit "cshx2_articles", // table source "DESIGNATION", // colonne source 42, // ID de l'article LANGUE_ANGLAIS, TYPE_MOT_NOM ) SI bProcessing ALORS Info("Traduction enregistrée") SINON Erreur(sErrorMessage) FIN
Mode 2 — traduction avec genre grammatical
Cas d'usage : enregistrer une traduction féminine d'un adjectif qualificatif.
"Belle", "cshx2_articles", "QUALIFICATIF", 42, LANGUE_FRANCAIS, TYPE_MOT_ADJECTIF, 2 // 2 = féminin ) // La forme masculine "Beau" peut être enregistrée séparément avec genre = 1 // → deux lignes distinctes coexistent dans cshx2_traductions
Mode 3 — boucle d'import de traductions
Cas d'usage : import en masse depuis une source externe (fichier, API, etc.).
tabImport[i].sTexte, tabImport[i].sTable, tabImport[i].sColonne, tabImport[i].nIDTuple, tabImport[i].nLangue, tabImport[i].nTypeMot ) SI bProcessing = Faux ALORS Trace("Échec ligne " + i + " : " + sErrorMessage) // Continuer ou interrompre selon politique d'import FIN FIN
Mode 4 — gestion défensive de l'erreur d'intégrité