Localization and workflow-state label translations

Localization controls the human-readable labels for Beleg (expense receipt) workflow states and Beleg types. Internal keys stay stable while you translate the visible text per language, with an automatic fallback to the default language when a translation is missing. This article explains the label catalog and the update workflow.

Required permission

Reading labels requires settings:manage. Saving labels also requires settings:manage and the SystemAdmin role — a custom role with only the permission receives a 403 (UNAUTHORIZED) on save.

What can be translated

The catalog covers two groups of stable internal keys:

• Workflow states: Draft, Submitted, In Review, Needs Clarification, Rejected, Approved, and Paid.
• Beleg types: fuel, maintenance_repair, toll, insurance, leasing, parking, washing, and other.

You translate the label; you never change the key. Rules, transitions, and reports continue to use the internal keys, so a translated label is purely presentational.

Default language and fallback

The default language is English (en). When you request labels for a language, the platform returns the requested translation for each key. If a key has no translation in that language, it falls back to the default label; if there is no default either, it falls back to the raw key. Whenever any fallback is used, the response includes the message "Translation unavailable, showing default" so you know some labels are not yet localized.

Note: Language codes are normalized to the neutral language. A request for de-DE is treated as de, so you maintain one German set rather than one per region.

Update labels

1. Open the Belege configuration localization area (under /admin/belege-configuration).
2. Select the language you are editing.
3. For each key, enter the translated label.
4. Mark an entry as default when it should serve as the fallback for other languages.
5. Save. You must submit at least one label.

Each submitted item carries an internal key, a language code, a label, and an optional default flag. Existing entries for the same key and language are updated in place; new ones are created. Only recognized keys are accepted — an unsupported key is rejected with a validation error.

Tip: Maintain a complete default (English) set first. Because other languages fall back to the default, a full default set guarantees no user ever sees a raw internal key.

Auditing

Every save records telemetry and an audit event (of type localization-update) linked to the active configuration version, capturing who made the change, when, and the submitted items. This gives you a traceable history of label changes alongside configuration changes.

Warning: If the localization store is unavailable, reads and writes return a 503 with "Localization store is not available". This usually means the underlying schema has not been provisioned yet; contact your platform administrator rather than retrying.

Related

• Belege configuration overview and publishing a version
• Default language settings (DE and EN)
• System configuration overview and access