This article provides best practices for teams that are responsible for creating and managing guides that will be displayed in multiple languages. Your organization may have an internal checklist that is used whenever a new guide is created and published. If you are using the localization feature, we recommend adding some localization-specific items to that checklist. This helps to avoid errors and reduces the amount of time needed to localize each guide. If you are new to localization and need a comprehensive overview of our localization functionality, see this Localization article for more information.
Plan ahead
Before starting the localization process, create a clear plan of action. Identify the languages you want to support and determine the scope of the localization effort. Is this language already set up in your subscription and you just need to create new translations for specific guides, or do you also need to set up the language as a supported language for the subscription?
Tip: We highly recommend finalizing the content of your guide before you start the localization process.
Settings
The target language code in the XLIFF file needs to match the language preference metadata value for the intended language. To adjust this, navigate to Settings > Subscription Settings > Applications, select your application, App, and then select Localization settings.
Target fields
All <target> fields in an XLIFF file must have a value, even if you are copying the same information from the <source> field.
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>
Third-party applications
Although there are multiple tools available for content translation and localization, some tools can potentially cause XLIFF files to be incompatible when uploading to your guide. Although we doesn't recommend any particular translation tool or service, or provide translation for Guide content, we have seen many customers successfully use Crowdin, Xliff Editor, and Smartling.
Cloning guides
If an already translated guide is cloned, the new copy of the guide needs to be translated again in your guide. Unfortunately, the XLIFF file from the original guide won’t be compatible with the new copy of the guide. You must export the XLIFF file from the new copy of the guide for translation.
Videos
Video links that use non-Unicode characters need to be wrapped within a CDATA tag in the <target> field to display correctly.
Example
<trans-unit id="ID string">
<source> <![CDATA[https://www.youtube.com/watch?v=videoIdGoesHere]]></source>
<target><![CDATA[https://www.youtube.com/watch?v=videoIdGoesHere]]></target>
<note> interst.io.VideoPlayerView </note>
</trans-unit>
Localization limitations
If the guide uses the Guide badge icon (if set to custom text), this section of the guide is not translated and appear in the default language. The other portions of the guide are translated.
Preview your guide
You can preview your guide to see how it looks with a different language using the imported XLIFF file. Select the required language from the Viewing dropdown within the guide settings.
Alternatively, you can also select Preview and then select a language from the dropdown.
Maintenance
Audit your XLIFF file
If you make additional content edits to a guide after you’ve already uploaded an XLIFF file, you must upload a new file. Modifying a guide can change the IDs within the XLIFF file so that the original imported translation file no longer aligns and causes an error. This also applies to new modules created in the Resource Center. You must upload a new translation file for the Resource Center if you add or remove modules.
For more information about localization, troubleshooting, and working with XLIFF Code see the Localization article, the Error: XLIFF translation file failing article, and Working with XLIFF Code.