How do I localize text and error messages in Piano Identity Management templates?

Localizable text in Identity Management falls into three categories with different editing flows: literal text in the template HTML (edited in the template), strings wrapped in ... tags (edited via the central Localization tool), and system-injected strings from Piano JS — including most validation messages (edited only through Piano's backend translation catalogue, which has a longer turnaround).

The three buckets of localizable text

If you cannot find a string in Manage → Localization search, it is almost certainly a system-injected string in the third bucket — request a translation update from Support.

Enabling Localization

Localization is a per-application feature. If it is not active on your application:

1. Go to Manage → Localization in the Composer dashboard.

2. If you do not see it, contact Piano Support to enable Localization across your application(s).

Once enabled, you can browse strings by language or search by phrase.

Editing a string in the Localization tool

1. Open Manage → Localization.

2. Choose the target language (e.g. English (United States), German, etc.).

3. Use the search box to find the phrase you want to change. Wildcard matches help when only part of the string is unique.

4. Edit the key with your replacement text.

5. Save.

Changes can take a few hours to a couple of days to appear on the frontend. If they do not appear:

• Confirm the change was actually saved.

• Clear your browser cache or use a private window to bypass CDN caching.

• Wait — the translation service updates every three business days.

Customizing error messages

By default, Piano shows generic error messages such as That combination of email and password is not recognized (intentionally generic to prevent email-enumeration attacks). To soften or rebrand the wording:

1. Navigate to Manage → Localization.

2. Pick your language.

3. Search for the exact phrase, e.g. That combination of email and password is not recognized.

4. Edit the key value to your desired text.

5. Save.

This works for error messages that are present in the Localization catalogue. Some validation messages displayed within the component are NOT editable here — see the next section.

system messages

Many error messages rendered inside are managed by Piano's backend translation catalogue rather than the per-account Localization tool. These are global system-level validation messages.

Two ways to translate or change them:

1. Backend Translation Update (permanent). Send Piano Support the exact English source text and the desired translation for each target language. The change is added to the backend catalogue and typically goes live in 2–4 business days as part of the regular release cycle. This is the right long-term fix.

2. Immediate Template Override (workaround). Override the message directly in your template by wrapping replacement text in a translation tag, then defining the translation:

html Your error message here 

Add the translation via Manage → Localization → Strings. Caveat: this override may be replaced or invalidated if the base template is updated in the future.

If you cannot find an error message in Manage → Localization at all, it is a system-injected string — contact Support to request the backend translation.

Placeholders in error messages

Translation strings sometimes include positional placeholders such as {0} for dynamic substitution. When providing a translation, preserve all {0}, {1}, etc. placeholders exactly as they appear in the English source. Without them, the message will display incorrectly or the dynamic value will be lost.

When a backend translation does not appear after release

If a translation has been promised live and is still missing in the UI, escalate to the Support team — there may be an underlying code issue (a token mismatch, a release that did not pull the catalogue, or a missing {0} placeholder breaking the substitution).

Translation update cadence

• Localization tool string edits: typically take effect within a few hours to a few days. The backend translation service runs every three business days.

• Backend catalogue updates (system messages): 2–4 business days as part of the regular release cycle.

• Code freezes: only critical bug fixes ship during a code freeze. Non-critical translation updates may be delayed until the freeze ends.

When a deadline matters, plan around the 3-business-day cadence.

Localizing custom-form text

Custom Forms (used inside Piano ID custom form and similar templates) expose a "title" and "ID" field that are intended for internal reference only. They are NOT displayed to the end user.

To show a title or label to users, add it explicitly in the form's HTML:

<p>Your Desired Title Here</p>

If you want that title localizable, wrap it in a translation tag:

<p><t>Your Desired Title Here</t></p>

Then add the translation under Manage → Localization → Strings.

Also be careful not to wrap the text inside a directive that would unintentionally hide it — hideIfInsideCheckout, for example, will suppress the element when the form is rendered inside the checkout flow. Configure these directives intentionally based on where the form should appear.

Editing template text and CSS together

The Piano ID Layout template's editor exposes both an HTML tab and a CSS tab. To customize how localized text appears (color, size, weight), use the CSS tab — for example, override the relevant text class:

.lead { color: #333; font-size: 18px; }

This is the right place for typographic adjustments alongside translation edits. Confirm you have access to the template editor for the application you want to change.

Localizing dynamic content (subscription names, user data)

When a localized string contains dynamic content that Piano interpolates at runtime (e.g. a subscription name in an auto-renewal notification), the translation must preserve the slot that holds the dynamic value. Concretely:

• The German translation of The auto-renewal for your subscription has been enabled is Die automatische Verlängerung für Abonnement wurde aktiviert, with the subscription name inserted automatically by Piano.

• Translations of password-reset errors must reflect the language-appropriate phrasing: Email not valid in German is E-Mail-Adresse nicht gefunden, which translates more closely to "email address not found".

When you adjust a localized string with dynamic content, test it end-to-end so the dynamic value renders in a grammatically correct position.

Global, language-wide changes

A change that should affect every customer on a given language locale (not just your application) generally cannot be made self-service. It must go through Piano's product feedback process or be applied to the central template by Piano. Examples include "every German customer sees X instead of Y" for a default system string.

Updating language on Identity Management modals — quick checklist

When you change copy on the registration or sign-in modal and the change does not appear:

1. Verify the change is saved in the correct place (template HTML vs. Localization vs. backend catalogue).

2. Clear the browser cache, or test in a private window.

3. Confirm the template version is published.

4. Wait through the appropriate cadence (immediate / ~3 business days / 2–4 business days).

5. If it still does not show, ensure the phrase is tagged for localization with ... if you expect Localization-tool control.

Manual additions via Weblate

For strings on the Piano ID Login Page that are not yet present in the Localization search, Piano uses Weblate as its translation-management backend. New translations added via Weblate can take up to 3 business days to be reflected in the UI. If you encounter a missing translation:

• Confirm the phrase is correctly tagged (...).

• Request the addition via Piano Support, who will route it through Weblate.

Localization keys and duplicate-looking entries

A localization key can appear with multiple seemingly-different content values when the same key is used in different contexts — for example in an Offer template vs. a Identity Management template/form. This is not an error: Piano supports context-specific translations so that a single key resolves to different text depending on where it is rendered.

To test how a key will appear in a specific context:

1. Insert the key into the target template.

2. Preview the template.

3. The localized value displayed in preview is the value that will render in production for that context.

If a translation is missing or wrong in one template but correct in another, check that you are editing the key for the correct context.

Picking the right My Account template

When updating translations and styling in My Account templates and your application uses Identity Management authentication, edit the Piano ID profile in My Account template (not a generic My Account template). To confirm two applications are using the same template version, compare template IDs or the last-edited timestamps in the dashboard. Allow a few minutes for CDN refresh and verify in a private window.

Translation strings wrapped in ... are updated by Piano's back-end translation service every three business days. If translations do not appear immediately, remove any context attribute from the translation tags so the existing translation token maps correctly. Some strings — error messages, ARIA labels — are injected by Piano JS and can only be changed through the central translation tool.

Last updated: July 03, 2026