Betterworks Guides: Localization



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. Guides can be written in your preferred language, content is then exported as an XLIFF file (the standard format for translation data), translated outside of Betterworks Guides, and then imported back into Betterworks Guides. Betterworks Guides uses the language metadata the Adopt Partner (Betterworks) passes through in the installation snippet or browser metadata to display the appropriate language to your user.

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 with the exception of 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 are 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.

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

Localization is accessed from the Guide Details page of the Guide you're translating.

1. Find the Localization tile in Guide Details.

2. Click Edit to manage Localization for this Guide.

3. Click 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 is included in the same file.

Authored Language is used to change the source language in the XLIFF file. It is typically US English but can be changed to any of the languages setup in Localization Settings. Edit the Authored Language if it does not match the language the Guide was written in.

Note: Companies who translate their apps and app content usually have a Translation Department or service who perform the text translation. This department uses dedicated translation tools to assist with the process, like Poedit and Xliff Editor. Betterworks doesn't recommend any particular translation tools, translation services, 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 our adopt partner (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 Betterworks Guides is ready for translation and does not 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 will not 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. It's important that each trans-unit is translated individually. Translating multiple blocks of text in a single trans-unit is unsupported. 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>  



  <file... source-language="en-US" target-language="fr-FR">


     <trans-unit id="ID String">








Betterworks Guides 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">


<group id="ID STRING">


<trans-unit id="ID STRING">

<source>How likely are you to recommend us to a friend or coworker?</source>









Import the Translation

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

1. Click Edit to manage Localization for this Guide.

2. Click 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 will still be available to update the Translated Language later.

3. Click Done to close the Edit view of the Localization Tile.

Note: The XLIFF file must match to the corresponding Guide. If the content of the XLIFF file does not match the Guide, the import will fail. The upload validates that all target containers have translated content. If some target containers are empty, a notification informs you that some content may be missing but the file is still imported.

Test & Preview Your Translated Guides

Use the Viewing language dropdown at the top of the Guide Settings to preview your Guide in your translated language.

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.


What language file type is supported?

XLIFF 1.2 format only.

Which languages are supported?

Afrikaans (af)

Danish (da)

Estonian (et)

Greek (el)

Norwegian (no)

Spanish (es)

Vietnamese (vi)

Amharic (am)

Dutch (nl)

Filipino (fil)

Hindi (hi)

Polish (pl)

Spanish - Chile (es-CL)

Zulu (zu)

Bulgarian (bg)

Dutch - Belgium (nl-BE)

Finnish (fi)

Hungarian (hu)

Portuguese (pt)

Spanish - Latin America (es-419)

Catalan (ca)

English (en)

French (fr)

Indonesian (id)

Portuguese - Brazil (pt-BR)

Spanish - Mexico (es-MX)


English - Australia (en-AU)

French - Belgium (fr-BE)

Italian (it)

Portuguese - Portugal (pt-PT)

Spanish - Spain (es-ES)

Chinese - Hong Kong (zh-HK)

English - Canada (en-CA)

French - Canada (fr-CA)

Japanese (ja)

Romanian (ro)

Swahili (sw)


Chinese - PRC (zh-CN)

English - Ireland (en-IE)

French - France (fr-FR)

Korean (ko)

Russian (ru)

Swedish (sv)


Chinese - Taiwan (zh-TW)

English - New Zealand (en-NZ)

German (de)

Latvian (lv)

Serbian (sr)

Thai (th)


Croatian (hr)

English - UK (en-GB)

German - Austria (de-AT)

Lithuanian (lt)

Slovak (sk)

Turkish (tr)


Czech (cs)

English (US) (en-US)

German - Switzerland (de-CH)

Malay (ms)

Slovenian (sl)

Ukrainian (uk)


Note: Right-to-left languages (i.e. Hebrew and Arabic) are not supported yet.

Does Betterworks translate the Guides for me?

No. We provide you with an XLIFF file that you can translate but we are happy to help with upload.