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 visitor. This feature is available for web guides, mobile guides, and the Resource Center.
Like web guides, any customer using the mobile SDK can translate native mobile guides. The SDK sends the device's language in the Language metadata field, just like the web SDK. 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 and Resource Center 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
- Subscription admins can access and manage localization settings in subscription settings.
- Guide creators can edit translations.
- Your app must be on web SDK version 2.15.15 or greater.
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, then 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 or the Resource Center in the default language when their translated language is unavailable. This could be because that language hasn't yet been translated or isn't set up in your Pendo subscription.
Note: This is an important setting that prevents a visitor from seeing a guide or the Resource Center if they have a language setting that doesn’t match your preferences.
For example, users might set their preferred language to Korean in their browser even though they can read English. This user wouldn't see any guides or the Resource Center unless they were translated into Korean.
Turn the button on to display guides and the Resource Center using the default language, indicated in Supported Languages.
Turn the button off to hide guides and the Resource Center if the available translated languages don't match the visitor's language metadata.
When Enable Locale Fallback is turned on, visitors whose locale doesn’t have a translation but whose parent language does will see the guide or Resource Center in the parent language. If the parent language isn’t available, the fallback follows the behavior described in Show Default Language if Translation is Missing. For example, if a visitor uses the es_MX (Spanish-Mexico) locale, but there's no translation available, it shows the guide in es (Spanish).
To find this setting in Pendo,
- Go to Settings > Subscription settings.
- Open the Applications tab, then select the relevant app.
- Open the Localization Settings tab, then look under the Missing Translation Language Behavior section.
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 within a guide's 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
Resource Center localization covers the Resource Center name, module titles and subtitles, and the names of any guides included in the Resource Center. You can translate this content directly in the app or import an XLIFF file. Guide content itself must be translated separately for each guide.
To localize a Resource Center, go to Guides > Resource Center in the left-side menu and open the localization tile. The translation workflow is the same as for guides.
If a guide name is missing from the translation file, the Missing Translation Language Behavior setting applies.
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
Pendo uses Google Translate for localization and supports every language available within it. The language dropdown in Google Translate provides a full list of supported languages.
The supported language file type is XLIFF 1.2 format only.
Note: Right-to-left languages, for example, Hebrew and Arabic, aren't supported yet in guide translations, only in Resource Center translations. You can create guides for right-to-left languages for both web and mobile. For more information, see Use right-to-left languages in guides.
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:
- The name of your Pendo subscription.
- The name of the application in Pendo.
- The supported language that you'd like to be the default language.