Overview

Data Translations

Record-level content translation on the #/_record_field_translations/list route for multilingual support of business data.

Scope

Translations for field values on specific records (not just UI labels).
Variant management per language on entity/table/column.
Typical use: product descriptions, operational notes, commercial texts, content displayed in list/detail/report.

Main Client-Side Features

Automatic rendering of the translated value when the user language changes.
Fallback to the base record value when the specific translation is missing.
Compatibility with list-grid, form/edit popup, data-driven archetypes, and report/export.
Consistent update after saving/editing translations without component changes.

Main Server-Side Features

Join/fetch of record-field translations in dynamic queries (getFlatRecordData) when configured.
Persistence by composite keys (entity, record id, field, language).
Transactional consistency between base value and translated variants.
Authorization enforcement on data translation modifications.

Usage Pattern

Insert translations in #/_record_field_translations/list.
Correctly associate entity/record/field/language.
Verify in the target route that the active language displays the translated value.
When a translation is missing, verify fallback to the original value (baseline).

Global configuration (appsettings.json)

The feature is driven by the RecordTranslations section in appsettings.json (read server-side at bootstrap). When Enabled=true, the backend joins the translation table in getFlatRecordData and applies a fallback to the base value when no variant exists for the current language.

Snippet 1JSON

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

Enabled: global switch. If false, no join → getFlatRecordData returns only base values. The client uses this flag (exposed via AuthConfig.recordTranslationsEnabled) to decide whether to reload the route on language change.
DefaultTableName: SQL table that stores (entity, record_id, field, language) → translation. Convention: _record_field_translations.
TranslationJsonFieldName: JSON column name where multiple translated fields per record coexist (alternative to the composite-key tabular model).
DefaultLanguage: "base" language of records; used as fallback when the user's language has no variant.
FieldNames: global list of fields candidate for translation (can be overridden per route via md_props_bag below).

Changes to this section require an app restart (change impact = Restart in the AppSettings panel).

md_props_bag (per-route override)

Each route can have its own serverProperties.RecordTranslations block inside the metadata table md_props_bag (_metadati__tabelle.md_props_bag). Use it when a single table wants to:

enable translations only for itself (even with the global flag off),
disable translations only for itself (with the global flag on),
override DefaultLanguage or the FieldNames list with a table-specific set.

Snippet 2JSON

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

Resolution precedence (server-side): md_props_bag.serverProperties.RecordTranslations (if present) → appsettings RecordTranslations (global) → code default.

Effects on language change (client)

When Enabled=true (global or per-route override), on language change the client reloads only the datasource of the currently displayed route via getFlatRecordData — internal metadata datasources (styles, authorizations, etc.) are not reloaded because they do not vary per language. When Enabled=false, zero data re-fetches: labels are handled by the translate pipe which updates autonomously from _wuic_translations.

Client/Server Effects per Key Property

entity/table route: client routes the context; server filters the translation domain.
record id: client maintains record binding; server resolves the target row.
field name: client knows where to inject the translated text; server correctly maps the column.
language code: client switches language immediately; server selects the correct variant.
translated value: client displays localized output; server saves and returns a consistent payload.

Best Practices

Define a single fallback policy (e.g., user language -> tenant default -> base value).
Avoid duplicate translations for the same composite key.
Track translation updates with audit (user/date) in enterprise environments.
Always test edge cases: missing translation, unsupported language, deleted record.