Localization

Last updated: January 21, 2025 13:38

Companies expanding into global markets or supporting a multilingual user base need to publish content in multiple languages. Localization makes it easy to deliver in-app messages in a variety of languages. You can write your guide content and the Resource Center content in your preferred language and then export the content as an XLIFF file (the standard format for translation data), which is translated outside of Pendo, and then import it back into Pendo. Pendo uses the language metadata you pass through in the install script or browser metadata to display the appropriate language to your user. This feature is available for web guides and mobile guides.

Native mobile guides can be translated just like web guides by any customer using the mobile SDK. The SDK sends the device's language in the Language metadata field, just like the web agent. You can also set up localization to use any alternative user metadata field for the device's language in the application settings.

Note: You can leverage AI to simplify the localization of your guides into any of the languages that are supported in your app, if the setting to allow AI to generate translations is enabled in your subscription. For more information, see Localize your guides using AI.

Requirements

Pendo Admin users can access and manage Localization settings in Subscription Settings.
Pendo Users with Create Guides from layouts or from scratch can edit translations.
Agent Version 2.15.15 or greater. Localization leverages the Visual Design Studio, this is the minimum version required for this feature.

Set up localization settings

Localization Settings are app-specific and can be enabled for individual apps in a multi-app subscription.

Go to Settings > Subscription Settings in the Settings menu and select your app.
In the Localization Settings tab, enable Localization. This shows the Localization Settings applied to all guides in that app.

Note: Guides created in the Classic Designer can't be localized. The Missing Translation Language Behavior setting doesn't block Classic Designer guides. Users can still see Classic Designer guides even if the setting is set to hide them if the users’ language hasn't been translated.

Language preference metadata

Pendo displays the appropriate language to visitors based on their local metadata. You can use the default language metadata collected from the visitor's browser or define a custom language metadata value through the install script and data mapping settings. You can choose the metadata field name and its values.

Note: Custom language metadata fields must use a name other than language. This name is reserved for browser language metadata and can't be replaced.

Select the language metadata value from the dropdown menu.

Note: Pendo recommends using your own values for analytics accuracy, but a visitor’s browser language metadata can be used if you don’t have another option.

Supported guide languages

You can add all the languages you need for guide translations based on the metadata Pendo collects.

To add a language:

Select + Add Language.
Select a language from the dropdown menu. The list shows all available languages and the default metadata value collected by the browser for that language.
Change the metadata to match your custom language metadata value if necessary.
Select Add to save the new language. Repeat this process until you've added all of your languages.

Supported Languages shows a list of all added languages. Hover over a language to show the Edit and Delete buttons.

Missing Translation Language Behavior

Missing Translation Language Behavior controls whether a visitor sees a guide in the default language when their translated language is unavailable for that guide. This could be because that language has not yet been translated or isn't set up in your Pendo subscription.

Note: This is an important setting that prevents a user from seeing a guide if they have a language setting that doesn’t match your preferences.
For example, users may set their preferred language to Korean in their browser even though they can read English. This user wouldn't see any guides unless they were translated into Korean.

Turn the button on to display guides using the default language, indicated in Supported Languages.

Turn the button off to hide guides if the available translated languages don't match the visitor's language metadata.

Note: This setting also applies to the guides in the Resource Center.

Translate your guide

Translate a guide by exporting the XLIFF file, adding the translation into the file, and importing the translated file back into the guide's localization details. The XLIFF formats translations for any text entered into a building block apart from unstructured text in images and code blocks. The alt text and URL used for images is available for translation in the XLIFF.

For example, text in a text block and button text is captured in the XLIFF, but text in an uploaded image isn't. If you have a translated version of the image hosted, you can replace the image URL in the XLIFF file, so the guide loads your translated image instead of the image added to the original Guide.

Localized link URLs can be added in the .xliff file. Each button link will have its own trans-unit; the localized link URLs can be added in the <target> element for that unit.

Always start with a completed guide with the final version of all text. The translation file doesn't update if you edit your guide content in Visual Design Studio after exporting your XLIFF file. You'll need to repeat the export, translate, and import process if you make content changes.

Localize an NPS guide

NPS is a guide and has a Localization tile on the guide's details page if localization is enabled. After you translate your NPS survey, responders see it in their native language. NPS emails aren't translated.

If you don’t see the Localization option, you might have an older NPS poll that needs to be upgraded. For more information about upgrading your NPS Guide, see Upgrading an existing NPS survey.

Note: You can also automate the localization of multiple guides through our localization API, enabling the export and import of up to 15 guides in bulk.

Localization is accessed in the Settings tab of the guide's details page of the guide you're translating.

In the Localization tile in Guide Details page, select Edit.
Select Export to download the XLIFF file for your guide so it can be translated.

This file contains your guide content as strings that can be translated into your desired languages. If it is a multi-step guide, strings from each step are included in the same file.

Authored Language is used to change the source language in the XLIFF file. It's typically US English but can be changed to any of the languages set up in Localization Settings. Edit the Authored Language if it doesn't match the language the guide was written in.

Tip: Companies who translate their apps and app content usually have a translation department or service that performs the text translation. This department uses dedicated translation tools to assist with the process, like Smartling or Xliff Editor. Pendo doesn't recommend any particular translation tool or service or provide translation for Guide content.

Working with XLIFF code

XLIFF is the industry standard file format for content translation and localization. It identifies the specific UI elements and text content, the original and translated languages, and the original and translated content. The XLIFF file exported from Pendo provides the code for all the translatable content in the entire guide. Each object is organized by <trans-unit> in the code. The file exported from Pendo is ready for translation and doesn't have a target language or any target content. If you need to translate into multiple languages, each language requires its own XLIFF file. A single file doesn't support translation into more than one target language.

A trans-unit is an individual block of text in the code. You may have multiple trans-units in a single guide step. Each trans-unit must be translated individually. Translating multiple blocks of text in a single trans-unit isn't supported. You can edit the translated phrasing in the XLIFF file for the target language to improve readability and formatting in the rendered version of the translated guide if needed.

source-language-"en-US" - Language code for the source content
target-language=" " - Language code the text is being translated into
<source></source> - Source content from the Guide written in the source language
<target></target> - The container where the translated text is entered for each <trans-unit>

Example

<xliff...>
   <file... source-language="en-US" target-language="fr-FR">
   ...
      <trans-unit id="ID String">
         <source>Hello</source>
         <target>Bonjour</target>
         <note>TextView</note>
      </trans-unit>
   ...
   </file>
</xliff>

Pendo XLIFF Code Sample

<xliff version="1.2" xmlns="urn:oasis:names:tc:xliff:document:1.2">
 <file original="ID STRING" datatype="pendoguide" 
  source-language="en-US" target-language="TRANSLATED LANGUAGE CODE">
 <body>
 <group id="ID STRING">
 <note></note>
 <trans-unit id="ID STRING">
 <source>How likely are you to recommend us to a friend or coworker?</source>
 <target>TRANSLATED LANGUAGE TEXT</target>
 <note>TextView</note>
 </trans-unit>
...
 </group>
 </body>
 </file>
</xliff>

Note: Some of the XLIFF code includes CDATA tags that are there to protect special characters in translation text from being interpreted as part of the code. The CDATA tags must be left in the XLIFF files so that special characters are displayed correctly in your guide. You must also wrap your translated text between the <target> tags with CDATA tags.

Import the translation

To activate the translated version of a guide, import the translated XLIFF file for the translated language into the Localization tile.

Select Edit in the Localization tile.
Select Import next to the Untranslated Language to upload the translated XLIFF file. The Untranslated Language should be the same as the target language in the file.

When the import is complete, the language moves from Untranslated to Translated. The Import button is still available to update the translated language later.
Select Done to close the Edit view of the Localization tile.

Warning: The XLIFF file must match to the corresponding guide. If the content of the XLIFF file doesn't match the guide, the import fails. The upload validates that all target containers have translated content. If some target containers are empty, a notification informs you that some content might be missing but the file is still imported.
If you encounter errors with the XLIFF file, see Error: XLIFF translation file failing for troubleshooting information.

Test and preview your translated guides

To preview your guide in your translated language, use the Viewing language dropdown in guide Settings, and then select Preview.

You can make changes to the XLIFF file and reimport it as many times as you need.

Publish the guide when you're satisfied with the translated version. If the guide is already public, the translation is available as soon as the import is complete.

View guide metrics according to language

You can view metrics for your guides according to selected languages. Navigate to your guide and select Guide Metrics. Use the filter to select the language dropdown option and choose a different language.

Localize the Resource Center

The process for localizing the Resource Center is the same as for guides.

To access the localization tile in the Resource Center, in the left navigation bar, go to Guides > Resource Center.

The Resource Center localization includes translations for the Resource Center name, module title and sub-titles, and any guide names included in the Resource Center. The guide's content is translated in the context of the guide itself.

If any guide name is missing from the translation file, the Missing Translation Language Behavior setting (see above) takes effect.

Update the Resource Center localization

If you make changes to the Resource Center or to a guide in the Resource Center, you must update the localization as follows:

Update only the Resource Center localization after:
- Adding a new module
- Changing a module's title or subtitle
- Adding new search keywords to a guide list module
- Adding a guide that has already been translated to a guide list or onboarding module
Update only an individual guide's localization after:
- Changing the content in a guide step
- Adding more guide steps to an existing guide
- Adding an Announcement to the Resource Center
Update both the Resource Center and individual guide's localization when you create a new guide and add it to the Guide list or the Onboarding module.

Available translations in the Resource Center XLIFF file

All module titles
All module subtitles
Guide name, keywords, search bar, and search results text in Guide List modules
Guide name and step counter in Onboarding modules

Announcements and guide content, other than the name, are translated using Localization settings for the specific guide.

Note: The content of a Sandbox Module can't be translated with localization. The Localization tool can't pull text out of custom code. To deliver translated content in a Sandbox module, review the code and translate the content of the existing Sandbox module, create a new Sandbox module with the translated content, and use segmentation and language metadata to display the appropriate Sandbox module.

Language support and file type

The supported language file type is XLIFF 1.2 format only. The following languages are supported in Pendo:

Afrikaans (af)
Amharic (am)
Austrian German (de-AT)
Bengali (bn)
Bulgarian (bg)
Catalan (ca)
Chinese - Hong Kong (zh-HK)
Chinese - PRC (zh-CN)
Chinese - Taiwan (zh-TW)
Chinese(zh)
Croatian (hr)
Czech (cs)
Danish (da)
Dutch - Belgium (nl-BE)
Dutch (nl)
English - Australia (en-AU)
English - Canada (en-CA)
English - Ireland (en-IE)
English - New Zealand (en-NZ)
English - UK (en-GB)
English (en)
English (US) (en-US)
Estonian (et)
Filipino (fil)
Finnish (fi)
French - Belgium (fr-BE)
French - Canada (fr-CA)
French - France (fr-FR)
French (fr)
German - Austria (de-AT)
German - Switzerland (de-CH)
German (de)
German (de)
Greek (el)
Gujarati (gu)
Haitian Creole (ht)
Hindi (hi)
Hungarian (hu)
Icelandic (is)
Indonesian (id)
Italian (it)
Japanese (ja)
Kannada (kn)
Korean (ko)
Latvian (lv)
Lithuanian (lt)
Malagasy (mg)
Malay (ms)
Malayalam (ml)
Marathi (mr)
Mongolian (mn)
Norwegian (no)
Odia (or)
Polish (pl)
Portuguese - Brazil (pt-BR)
Portuguese - Portugal (pt-PT)
Portuguese (pt)
Romanian (ro)
Russian (ru)
Serbian (sr)
Slovak (sk)
Slovenian (sl)
South African (en-ZA)
Spanish - Chile (es-CL)
Spanish - Latin America (es-419)
Spanish - Mexico (es-MX)
Spanish - Spain (es-ES)
Spanish (es)
Swahili (sw)
Swedish (sv)
Swiss Italian (it-CH)
Tamil (ta)
Telugu (te)
Thai (th)
Turkish (tr)
Ukrainian (uk)
Urdu (ur)
Vietnamese (vi)
Zulu (zu)

Note: Right-to-left languages, for example, Hebrew and Arabic, aren't supported yet in translations. You can create guides for right-to-left languages for both web and mobile. For more information, see Design guides for right-to-left languages.

Change the default language from English (US) (en-US) to another supported language

You can change the default language to another supported language with the help of Pendo support. This process also updates the default language on all existing guides and removes any existing translations already attached. You'll also need to be prepared to re-import all existing translation files.

Contact Pendo Support and provide:

Your Pendo subscription
The Pendo application
The supported language that you'd like to be the default language