Localization

Last updated: August 21, 2024 09:53

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 installation snippet or browser metadata to display the appropriate language to your user. This feature is available for web and native mobile guides (v2).

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.

Language Preference Metadata

Pendo determines which language to serve visitors based on the Visitor’s local metadata. Use the default language metadata Pendo collects from the visitor's browser or set up a custom language metadata value in the Install Snippet and Data Mappings settings. The metadata field name and values of that metadata are up to you.

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

Select the language metadata value in 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

Select + Add Language to add all the languages you need for Guide translations.
Select the 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 is not 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 would not 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 is not. 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.

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 contents, the original and translated languages, and the original and translated content. The XLIFF file exported from Pendo provides the code for all 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 is not 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 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.

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.

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 cannot 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.

Frequently asked questions

Can the default language be changed from English (US) (en-US) to another supported language?

Yes, Pendo Support can change the default language to another supported language for you. This process also updates the default language on all existing guides and removes any existing translations already attached.

You will also need to be prepared to re-import all existing translation files. If you would still like to make this change, please contact Support and include:

Pendo subscription
Pendo application
Supported language that you would like to be the default language

How will turning on Localization affect my Classic Designer guides?

Guides created in the Classic Designer cannot be localized. The Missing Translation Language Behavior setting does not block Classic Designer guides. Users will still see Classic Designer guides even if the setting is set to hide them if the users’ language has not been translated.

What language file type is supported?

XLIFF 1.2 format only.

Which languages are supported?

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, are not 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.

Is this supported for Mobile guides as well?

Native mobile guides can be translated just like web guides by any customer using the mobile V2 SDKs.

The mobile SDKs send the device 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 language in the application settings.

Does Pendo translate the guides for me?

No. We provide you with an XLIFF file that you can translate.

Can I localize an NPS guide?

Yes. NPS is a guide and has a Localization tile on the guide's details page if localization is enabled. Once you translate your NPS survey, responders see it in their native language. NPS emails are not 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.

Can I analyze guides according to Language?

Yes. Navigate to your guide and select Guide Metrics. Using the filter, you can select the language dropdown option and choose a different language.