Overview

Traduzioni dati

Traduzione contenuti record-level sulla route #/_record_field_translations/list per supporto multilingua dei dati business.

Scope

Traduzioni per valore campo su record specifici (non solo label UI).
Gestione varianti per lingua su entita/tabella/colonna.
Uso tipico: descrizioni prodotto, note operative, testi commerciali, contenuti esposti in list/detail/report.

Feature principali lato client

Rendering automatico del valore tradotto quando la lingua utente cambia.
Fallback su valore base record quando manca la traduzione specifica.
Compatibilita con list-grid, form/edit popup, archetipi data-driven e report/export.
Aggiornamento coerente dopo save/edit traduzioni senza modifiche ai componenti.

Feature principali lato server

Join/fetch traduzioni record-field in query dinamiche (getFlatRecordData) quando configurato.
Persistenza per chiavi composte (entita, id record, campo, lingua).
Coerenza transazionale tra valore base e varianti tradotte.
Enforcement autorizzazioni su modifica traduzioni dati.

Pattern di utilizzo

Inserire traduzioni in #/_record_field_translations/list.
Associare correttamente entita/record/campo/lingua.
Verificare in route target che la lingua attiva mostri il valore tradotto.
In assenza traduzione verificare fallback al valore originale (baseline).

Configurazione globale (appsettings.json)

La feature e' pilotata dalla sezione RecordTranslations in appsettings.json (letta lato server al bootstrap). Quando Enabled=true, il backend effettua join con la tabella traduzioni in getFlatRecordData e applica il fallback al valore base in assenza di variante per la lingua corrente.

Snippet 1JSON

{
  "RecordTranslations": {
    "Enabled": true,
    "DefaultTableName": "_record_field_translations",
    "TranslationJsonFieldName": "translation_json",
    "DefaultLanguage": "it-IT",
    "FieldNames": []

Enabled: interruttore globale. Se false nessun join → getFlatRecordData ritorna solo valori base. Il client usa questo flag (propagato via AuthConfig.recordTranslationsEnabled) per decidere se ricaricare la route al cambio lingua.
DefaultTableName: nome tabella SQL che memorizza (entita, record_id, campo, lingua) → traduzione. Convenzione: _record_field_translations.
TranslationJsonFieldName: nome colonna JSON dove convivono piu' campi tradotti per record (alternativa al modello tabellare a chiavi composte).
DefaultLanguage: lingua "base" del record; usata come fallback quando la lingua utente non ha variante.
FieldNames: elenco globale di campi candidati alla traduzione (puo' essere sovrascritto per route via md_props_bag sotto).

Dopo modifiche alla sezione serve riavvio applicativo (change impact = Restart nel pannello AppSettings).

md_props_bag (override per route)

Ogni route puo' avere il proprio blocco serverProperties.RecordTranslations dentro md_props_bag della tabella metadata (_metadati__tabelle.md_props_bag). Serve quando una singola tabella vuole:

abilitare le traduzioni solo per se' stessa (anche con flag globale spento),
disabilitare le traduzioni solo per se' stessa (con flag globale acceso),
sovrascrivere la DefaultLanguage o la lista FieldNames con un set specifico per questa tabella.

Snippet 2JSON

{
  "serverProperties": {
    "RecordTranslations": {
      "Enabled": true,
      "DefaultTableName": "_record_field_translations",
      "TranslationJsonFieldName": "translation_json",
      "DefaultLanguage": "it-IT",

Precedenza risoluzione (server-side): md_props_bag.serverProperties.RecordTranslations (se presente) → appsettings RecordTranslations (globale) → default codice.

Effetti al cambio lingua (client)

Quando Enabled=true (globale o override per route), il client al cambio lingua ricarica solo il datasource della route correntemente visualizzata via getFlatRecordData — i datasource metadata interni (stili, autorizzazioni, ecc.) non vengono ricaricati perche' non variano per lingua. Quando Enabled=false, zero re-fetch di dati: le label sono gestite dalla pipe translate che si aggiorna autonomamente da _wuic_translations.

Effetti client/server per proprietà chiave

entity/table route: client instrada il contesto; server filtra il dominio traduzioni.
record id: client mantiene binding record; server risolve la riga target.
field name: client sa dove iniettare il testo tradotto; server mappa correttamente la colonna.
language code: client switch lingua immediato; server seleziona variante corretta.
translated value: client visualizza output localizzato; server salva e restituisce payload coerente.

Best practice

Definire una policy di fallback unica (es. lingua utente -> default tenant -> valore base).
Evitare traduzioni duplicate per stessa chiave composta.
Tracciare aggiornamenti traduzioni con audit (utente/data) in ambienti enterprise.
Testare sempre i casi limite: traduzione mancante, lingua non supportata, record cancellato.