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 in Trustdesk — a centralized system for all localized resources. Instead of editing raw JSON in the hosted pages area, you manage hosted page strings from the Translation Management UI, with schema validation, completion tracking, and support for multiple translation sets.
This gives instance administrators a single place 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
- Assign a translation set to an application via its hosted page layout
At a Glance
System overview
┌──────────────────────────────────────────────────────────────────────────┐
│ ADMIN (Trustdesk) │
│ │
│ Translations UI ──► localization-srv ──► CDN (locale files) │
│ (edit strings) (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:
- Setup — Hosted pages are registered as a localization resource with a schema and default translation set.
- Edit — An admin edits translations in Translation Management; changes are validated against the schema and published to CDN.
- Assign — A hosted page layout maps the hosted pages resource to a translation set; the application references that layout.
- Serve — At login or registration, hosted pages request configuration from
public-srvand 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.
Manage Hosted Page Translations
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.
Hosted pages support multiple translation sets. Use the default set unless you need a separate set for a specific brand or application.
Step 3: Edit Translations
- On the resource details page, select a translation set.
- 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.
Translation keys, descriptions, and UI hints come from the resource schema — you do not need a separate key reference list. Search and category filters in Translation Management help you find the string you need.
:::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.
:::
Step 4: Add a Locale or Translation Set
Add a locale to an existing set when you want to support a new language.
Create a translation set when you need a separate copy of hosted page strings (for example, a white-label brand). You can optionally copy from an existing set.
Step 5: Assign a Translation Set to Your Application
Translations take effect when the application uses a hosted page layout that points to the correct translation set.
In Trustdesk:
- Go to Branding → Hosted Pages Layout and open (or create) the layout used by your application.
- Under Resources, set the translation set for the hosted pages resource (key:
default-hosted-pages-webapp). - Go to Integrations → Applications, open your app, and set Hosted Pages Layout (
hosted_pages_layout_id) to that layout.
Example — hosted page layout (PUT /hostedpages-srv/hosted-page-layouts/{id}):
{
"description": "Consumer portal branding",
"layout": {
"hosted_page_group": "consumer-pages",
"primaryColor": "#f7941d"
},
"resources": {
"default-hosted-pages-webapp": {
"translationSet": "enterprise"
}
}
}
Example — application link (App Configuration API):
{
"client_id": "a1b2c3d4-e5f6-4789-a012-3456789abcde",
"display_name": "Consumer Portal",
"hosted_pages_layout_id": "layout-consumer-001"
}
Two applications can share one layout (same translation set) or use different layouts (different translation sets) while editing strings in the same hosted pages resource.
Step 6: Preview Hosted Pages
After saving translations:
- Open the hosted pages preview from Translation Management or the hosted pages area in Trustdesk.
- Map your application, select the response type, and copy the preview link.
- Open the link in a browser to verify the translated content.
How Translation Sets Reach Hosted Pages at Runtime
The translation set is configured on the hosted page layout and resolved at runtime when a user opens a hosted page. The hosted pages web app does not call localization-srv directly. See Runtime flow above for the sequence diagram.
| Step | What happens |
|---|---|
| 1 | User starts login; hosted pages receive a requestId. |
| 2 | Hosted pages call Public Page Information (GET /public-srv/public/{requestId}) for branding, providers, and page settings. |
| 3 | public-srv resolves the application and its hosted_pages_layout_id, including resources.default-hosted-pages-webapp.translationSet. |
| 4 | Hosted pages load the locale file for that translation set from CDN (bundled defaults merged with your overrides). |
To verify the assignment via API before testing in the browser:
- Layout —
GET /hostedpages-srv/hosted-page-layouts/{id}→ checkdata.resources.default-hosted-pages-webapp.translationSet. - Application —
GET /apps-srv/apps/{clientID}→ checkhosted_pages_layout_idmatches the layout above. - Runtime —
GET /public-srv/public/{requestId}after starting a login for that app → confirms the page bootstrap for the same client (translations are loaded separately from CDN using the resolved translation set).
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
| 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
| 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 |
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 resourcescidaas:localization_write— Write access for localization resourcescidaas: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.
:::