Translation and Language Management in Hosted Pages

---

Overview

Translations and languages appear across many parts of cidaas: emails and SMS, login and registration pages (hosted pages), consents, and fields.

Learn more about Hosted Pages Management.

Hosted page translations are managed through Translation Management — a centralized system for all localized resources. Instead of editing raw JSON in the hosted pages area, you manage hosted page strings with schema validation, completion tracking, and support for multiple translation sets.

:::note API-Only Feature Notice

Creating and managing multiple translation sets as well as assigning translation sets to applications via Hosted Page Layouts is currently supported via REST APIs only. Management of multiple translation sets and layout assignment via the Trustdesk Admin UI is planned for a future release. Currently, the Trustdesk UI supports editing translations for the default translation set.

:::

This gives instance administrators and developers the ability to:

• View and edit hosted page translations across all supported locales
• Override bundled default strings or add fully custom locales
• Track translation completeness (critical, warning, and total missing keys)
• Maintain multiple translation sets for different brands or use cases (via API)
• Assign a translation set to an application via its hosted page layout (via API)

At a Glance

System overview

┌──────────────────────────────────────────────────────────────────────────┐
│  ADMIN / API                                                             │
│                                                                          │
│   Localization API  ──►  localization-srv  ──►  CDN (locale files)       │
│   (edit strings/sets)   (validate & store)      (en.json, de.json, …)   │
└──────────────────────────────────────────────────────────────────────────┘

┌──────────────────────────────────────────────────────────────────────────┐
│  RUNTIME (user opens login / register)                                   │
│                                                                          │
│   Hosted Pages  ──►  public-srv  ──►  app-srv  (resolve layout + set)    │
│        │                                                                 │
│        └────────────►  CDN  (load locale file for assigned set)         │
└──────────────────────────────────────────────────────────────────────────┘

Configuration model — one app, one translation set

Resource: default-hosted-pages-webapp
│
├── Translation set: default          Translation set: enterprise
│   ├── locale: en                    ├── locale: en
│   └── locale: de                    └── locale: de
│
Hosted Page Layout: layout-consumer-001
└── resources
      └── default-hosted-pages-webapp
            └── translationSet: "enterprise"    ◄── pick which set this layout uses

Application: Consumer Portal  (client_id: a1b2…)
└── hosted_pages_layout_id: "layout-consumer-001"   ◄── links app to layout above

Two apps can share one layout (same translation set) or use different layouts (different sets) while editing strings in the same resource.

Runtime flow

  User          Hosted Pages       public-srv         app-srv            CDN
   │                 │                 │                 │                │
   │  open login     │                 │                 │                │
   │────────────────►│                 │                 │                │
   │                 │ GET /public/{requestId}           │                │
   │                 │────────────────►│                 │                │
   │                 │                 │ resolve layout  │                │
   │                 │                 │ + translationSet│                │
   │                 │                 │────────────────►│                │
   │                 │                 │◄────────────────│                │
   │                 │◄── page config (branding, providers, …)           │
   │                 │                 │                 │                │
   │                 │ GET …/enterprise/de.json (assigned set + locale)  │
   │                 │──────────────────────────────────────────────────►│
   │                 │◄── translations ──────────────────────────────────│
   │◄ localized UI ──│                 │                 │                │

How It Works

Hosted pages are a static translation resource in the localization platform. At runtime, the hosted pages web app loads translations through public-srv, which resolves the correct translation set for the application's client ID and serves the locale data via CDN.

Typical flow:

1. Setup — Hosted pages are registered as a localization resource with a schema and default translation set.
2. Edit — Edit default translations in Trustdesk Translation Management, or use the localization-srv API to create custom translation sets and edit locale strings.
3. Assign — Map the hosted pages resource to a translation set in a hosted page layout via hostedpages-srv API, and link the layout to the application via apps-srv API.
4. Serve — At login or registration, hosted pages request configuration from public-srv and load the assigned translation set for the user's locale.

Terminology

Term	Explanation
Resource	A localizable entity in cidaas. Hosted pages are one resource among others (for example, field setup).
Translation set	A named collection of translations for a resource (for example, default, enterprise). A resource can have multiple sets for different brands or configurations.
Locale	A language code such as en or de. Each translation set supports one or more locales.
Bundled translations	Default strings shipped with cidaas hosted pages (English and German). You can override individual keys without providing every string.
Custom locale	A language beyond the bundled defaults (for example, French or Italian). All required keys must be translated for that locale.
Completion status	Metrics showing missing translations: critical (required keys), warning (optional keys), and total.

Note: Bundled defaults are available for English (en) and German (de). For other languages, provide translations for all required keys.

Managing Translations via Trustdesk UI

Trustdesk UI supports editing default translation strings for hosted pages.

Step 1: Open Translation Management

1. Log in to Trustdesk.
2. Navigate to Translations.

From the resource overview you can see all localization resources, their supported locales, translation sets, and completion progress.

Step 2: Select the Hosted Pages Resource

1. Open the hosted pages resource (for example, Default Hosted Pages / default-hosted-pages-webapp).
2. Review the resource details: supported locales, translation sets, and completion status per locale.

Step 3: Edit Translations

1. Select the translation set (e.g., default).
2. Click Edit Translations for the locale you want to work on.
3. Use one of the editors:
   • Table editor — Spreadsheet-style view with reference language, target translation, and missing/translated status. Best for bulk work across many keys.
   • Category editor — Keys grouped by page or feature (login, MFA, register, and so on). Best for focused edits within one area.
4. Edit translation values only. Do not change translation keys.
5. Save your changes. The system validates against the JSON schema before publishing.

:::warning Watch out

Do not edit translation keys or placeholders. Change only the displayed text values. Keys such as GUEST_LOGIN or LOGIN.WELCOME_HEADER must remain unchanged — only their values should be translated.

:::

---

Multiple Translation Sets & Layout Assignment (REST API Workflow)

Creating multiple translation sets and assigning them to applications via Hosted Page Layouts is currently available via REST APIs only.

Step 1: Define or Update a Translation Set (localization-srv)

Use localization-srv endpoints to create custom translation sets or update locale strings for a specific set:

PUT /localization-srv/resources/{resId}/sets/{setName}/locales/{locale}

Request headers:

• Content-Type: application/json
• Authorization: Bearer <access_token> (Requires scope cidaas:localization_write)

Example request payload:

{
  "GUEST_LOGIN": "Login as Guest",
  "LOGIN.WELCOME_HEADER": "Welcome to Enterprise Portal"
}

Step 2: Assign Translation Set to Hosted Page Layout (hostedpages-srv)

Configure the hosted page layout to use the desired translation set for default-hosted-pages-webapp:

PUT /hostedpages-srv/hosted-page-layouts/{id}

Request payload:

{
  "description": "Enterprise Portal Layout",
  "layout": {
    "hosted_page_group": "consumer-pages",
    "primaryColor": "#f7941d"
  },
  "resources": {
    "default-hosted-pages-webapp": {
      "translationSet": "enterprise"
    }
  }
}

Step 3: Link Layout to Application (apps-srv)

Associate the hosted page layout with the target application:

PUT /apps-srv/apps/{clientID}

Request payload:

{
  "client_id": "a1b2c3d4-e5f6-4789-a012-3456789abcde",
  "display_name": "Consumer Portal",
  "hosted_pages_layout_id": "layout-consumer-001"
}

Step 4: Verify the Configuration

To verify the setup programmatically before testing runtime behavior:

1. Check Layout Configuration: GET /hostedpages-srv/hosted-page-layouts/{id} Verify data.resources.default-hosted-pages-webapp.translationSet points to "enterprise".

2. Check Application Link: GET /apps-srv/apps/{clientID} Verify hosted_pages_layout_id matches your layout ID.

3. Check Runtime Bootstrap: GET /public-srv/public/{requestId} Confirms the page configuration and resolved layout settings for the login request.

---

Technical Integration

cidaas provides REST APIs for managing hosted page translations and assigning translation sets to applications. Translation content is managed through the Localization API (localization-srv). Layout and application linking use the Hosted Pages API and App Configuration API.

Translation Management APIs (localization-srv)

API	Description	Link
List Resources	Lists localization resources, including hosted pages.	View API
Get Resource Schema	Retrieves the JSON schema used for validation.	View API
List Translation Sets	Lists translation sets for a resource.	View API
Get Locale	Reads translations for a locale in a set.	View API
Update Locale	Updates translations (PUT full replace, PATCH partial merge).	View API
Bulk Update Locales	Updates multiple locales at once.	View API

Translation Set Assignment APIs (hostedpages-srv & apps-srv)

API	Description	Link
Get Layout by ID	Reads resources.{resourceId}.translationSet from a layout.	View API
Update Layout	Sets the translation set per resource on a layout.	View API
Get App Configuration	Reads hosted_pages_layout_id for an application.	View API
Update App Configuration	Links hosted_pages_layout_id to an application.	View API

Public API (Runtime)

API	Description	Link
Public Page Information	Bootstrap hosted page config for a requestId (branding, providers). Translations load separately from CDN using the resolved translation set.	View API

API Authentication

Localization APIs require OAuth2 client credentials with the following scopes:

• cidaas:localization_read — Read access for localization resources
• cidaas:localization_write — Write access for localization resources
• cidaas:localization_delete — Delete access for localization resources

For hosted page layout API scopes, see Hosted Pages Management — API Authentication.

For hosted page group and layout details, see Hosted Pages Management.

:::warning Need help implementing this?

Please contact us on our Developer Support Page.

:::