Version: 4.0.3

Translation and Language Management in Hosted Pages

Hosted pages Translations Trustdesk 4.x

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.

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

Configuration model — one app, one translation set

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

Runtime flow

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:

Setup — Hosted pages are registered as a localization resource with a schema and default translation set.
Edit — Edit default translations in Trustdesk Translation Management, or use the localization-srv API to create custom translation sets and edit locale strings.
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.
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

Log in to Trustdesk.
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

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

Step 3: Edit Translations

Select the translation set (e.g., default).
Click Edit Translations for the locale you want to work on.
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.
Edit translation values only. Do not change translation keys.
Save your changes. The system validates against the JSON schema before publishing.

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:

Check Layout Configuration: GET /hostedpages-srv/hosted-page-layouts/{id} Verify data.resources.default-hosted-pages-webapp.translationSet points to "enterprise".
Check Application Link: GET /apps-srv/apps/{clientID} Verify hosted_pages_layout_id matches your layout ID.
Check Runtime Bootstrap: GET /public-srv/public/{requestId} Confirms the page configuration and resolved layout settings for the login request.

Technical Integration

cidaas exposes two translation API surfaces. Use the one that matches your product version and integration style.

Surface	When to use	Base path
Localization API (4.0+, recommended)	Trustdesk Translation Management, multiple translation sets, completion tracking	`/localization-srv/...`
Hosted Pages Translations API	Direct locale JSON on hostedpages-srv; older versions; some Terraform / tooling paths named `translations`	`/hostedpages-srv/translations*`

Layout assignment and app linking still use the Hosted Pages API and App Configuration API.

Hosted Pages Translations API (`hostedpages-srv`)

Full OpenAPI: Hosted Pages API — Translations.

Method	Path	Scope	Purpose
`GET`	`/hostedpages-srv/translations`	`cidaas:hosted_pages_read`	List locale metadata (no full key map)
`POST`	`/hostedpages-srv/translations`	`cidaas:hosted_pages_write`	Create a locale map
`GET`	`/hostedpages-srv/translations/{localeId}`	`cidaas:hosted_pages_read`	Get nested translation map for a locale
`PUT`	`/hostedpages-srv/translations/{localeId}`	`cidaas:hosted_pages_write`	Replace an existing locale map
`DELETE`	`/hostedpages-srv/translations/{localeId}`	`cidaas:hosted_pages_delete`	Delete a locale
`GET`	`/hostedpages-srv/translationschemas`	`cidaas:hosted_pages_read`	Schemas + `bundledLocales` (`en`, `de`)

Optional on GET /translationschemas:

bundled=true|false — filter schemas
language=en — preferred language for schema titles (also accepts Accept-Language)

Example — list locales:

curl -sS -X GET "https://{host}/hostedpages-srv/translations" \
  -H "Authorization: Bearer <access_token>"

Example — create or update a locale map (nested keys, not flat strings only):

curl -sS -X POST "https://{host}/hostedpages-srv/translations" \
  -H "Authorization: Bearer <access_token>" \
  -H "Content-Type: application/json" \
  -d '{
    "locale": "de",
    "enabled": true,
    "translation": {
      "LOGIN": { "WELCOME_HEADER": "Anmelden" },
      "SUCCESS": { "GREETING": "Willkommen" }
    }
  }'

Use PUT /hostedpages-srv/translations/{localeId} when the locale already exists. Creating a duplicate returns conflict (service code 1002). Missing locale on GET/PUT/DELETE returns not found (service code 1003).

Translation Management APIs (`localization-srv`)

Use these for multi-set editing in cidaas 4.0+. Full OpenAPI: Localization API.

API	Description
List Resources	Lists localization resources, including hosted pages
Get Resource Schema	JSON schema used for validation
List / create translation sets	Named sets such as `default` or `enterprise`
Get / update locale	Read or write locale strings in a set (`PUT` replace, `PATCH` merge)
Bulk update locales	Update several locales in one call

Scopes: cidaas:localization_read, cidaas:localization_write, cidaas:localization_delete.

Translation set assignment (`hostedpages-srv` & `apps-srv`)

API	Description	Link
Get / update layout	Set `resources.{resourceId}.translationSet` on a hosted page layout	Hosted Pages API
Get / update app	Set `hosted_pages_layout_id` on the application	App Configuration API

Layout scopes: cidaas:hosted_pages_layout_read / _write / _delete.

Public API (runtime)

API	Description	Link
Public page information	Bootstrap hosted page config for a `requestId`. Locale files load from CDN using the resolved translation set.	Public Service

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

Need Support?

Please contact us on our Developer Support Page.

Overview​

At a Glance​

System overview​

Configuration model — one app, one translation set​

Runtime flow​

How It Works​

Terminology​

Managing Translations via Trustdesk UI​

Step 1: Open Translation Management​

Step 2: Select the Hosted Pages Resource​

Step 3: Edit Translations​

Multiple Translation Sets & Layout Assignment (REST API Workflow)​

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

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

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

Step 4: Verify the Configuration​

Technical Integration​

Hosted Pages Translations API (hostedpages-srv)​

Translation Management APIs (localization-srv)​

Translation set assignment (hostedpages-srv & apps-srv)​

Public API (runtime)​