Skip to main content

Guidelines for translation vendors

ben terris.jpg
Written by Ben Terris
Program Manager at MindTouch
This page applies to:MindTouch Responsive

This article assists translation vendors with processing documentation exported from a customer's MindTouch site.

Files and package structure

Consider the following before making changes to a customer's file (click to view details):

►  File formats
The MindTouch export package includes an array of file formats, including .html, .png, .json, .csv, .dat, .css, .mtarc, .xml and other associated files.

important note   Do not translate, or otherwise modify .dat, .css, .mtarc and .xml files.

►  Customer designated files

Site administrators can use the classification translationstatus: to specify which .html pages should and should not be translated. We recommend the following options:

  • translationstatus:notranslate
  • translationstatus:queued
  • translationstatus:inprogress
  • translationstatus:complete

The translationstatus: classification would be included on the bottom of each .html page, under the heading Page Tags. The classification is always preceded by the <a mt-export-translate="no"> attribute.

►  Page deletion, page addition and hierarchy persistence
The package hierarchy is referenced as part of the export file package.xml. Modifications to the hierarchy in package.xml, additions of new pages, or deletions of existing pages may cause an error in the import process.

important note   Do not delete or add pages in the exported package.

►  Features in archives and associated files
The following archives and associated files are unique to MindTouch.  Those in green include translatable content and those in red do not.
Archive file type File name Translatable?
Manifest package.xml red checkmark
Site structure hierarchy.dat red checkmark
Groups groups.dat red checkmark
Templates page.html green checkmark
Content (pages, tags, attachments, page properties, file properties) page.html green checkmark
Permissions security.dat red checkmark
Guide tabs guideTabs.json green checkmark
Context IDs contextswithmaps.csv green checkmark
Query recommendations queryrecommendations.csv green checkmark
Learning paths learningpathpages.csv red checkmark
  learningpaths.csv green checkmark

►  Unzipping the file for translation

Here are two compression tools that work well when unzipping your MindTouch archive:

►  Packaging the file for import

When compressing your MindTouch archive, make sure to grab the appropriate files. Select the following files:


important note   Do not zip the parent folder. Your archive will not import successfully!

Blacklisted (non-translatable) content

important note   MindTouch does NOT support changes made to blacklisted contentTo maintain the integrity of the MindTouch site and to ensure MindTouch can support translated content, do not translate any of the content listed below.

Click on the non-translatable items below to view details:

►   mt-export-translate="no" attribute
Do not translate content in page.html that includes the"no". Modification of content associated with this attribute may cause errors upon import.
►  <pre> sections
Since MindTouch keeps most custom code (DekiScript, JavaScript, CSS) in <pre> tags, do not translate anything in a <pre> tag. Also, leave DekiScript text inside double curly braces {{dekiscript}} untouched.
<pre>These sections are used for MindTouch code and should not be translated or removed</pre>
►  <head> sections
This <head> section is MindTouch metadata and should not be translated. 
    <meta name="mt-name" value="value"></meta>
    <title>My Page</title></head>

  NOTE:  The <title> in this section has no effect on the name of the page. A page title can only be changed by translating the <h1> header.

►  Conditional content
While conditional content can be translated, the MindTouch proprietary code below should remain unchanged.
<div class="mt-style-conditional style-wrap" if="user.anonymous">
    <p>Conditional content!</p>
►  Inline DekiScript
Proprietary DekiScript code (in double curly brackets) should remain unchanged.
{{ if(user.anonymous) { "Hello Stranger!"; } }}
►  Structured tags
Do not translate tags containing a colon (:. These structured tags are predefined in the system, and translated versions are not understood by MindTouch. In the example below, the text article:stage should not be translated.
<p class="template:tag-insert">
    <strong>Page tags: </strong>
►  URLs
The MindTouch export format includes a URL and title for each page. Whether the path and page title are identical or not,  do not translate URLs. Maintaining the URL structure is crucial for auto-relating multilingual content during future information architecture developments. The following example demonstrates how a URL and title should look before and after a translation:
  Before translation After translation
URL <Company domain>/security/product_guide/get_started <Company domain>/security/product_guide/get_started
Title Get started Introducción


Whitelisted (translatable) content

  NOTE:  You can safely translate the following whitelisted MindTouch elements. 

Click on the translatable items below to view details:

►  Page titles
Translate page titles (the display name of the page) by translating the <h1> text.
<h1 class="mt-export-title">My Page</h1>

important note   Do not modify the "mt-export-title" class.

►  Conditional content
Conditional content inside <p> tags is translatable.
<div class="mt-style-conditional style-wrap" if="user.anonymous">
    <p>Conditional content!</p></div>

important note   Do not modify any div attributes such as if="user.anonymous".

►  Tags
Tags are displayed at the bottom of a page. Verify whether tags are to be translated. Since tags are often used to categorize and organize pages, it may not be desirable to translate all tags.
<p class="template:tag-insert">
    <strong>Page tags:  </strong>

important note    Do not modify the class name template:tag-insert as it is an important MindTouch element. Only translate text inside <a> tags.

►  Guide tabs
Guide tabs are found in the guidetabs.json file. Only translate templateTitle content. (In the example below, only the text "Article directory" and "Tag directory" should be translated.)
    "guid": "1ee90735-0631-d747-178f-402f3b263cb7",
    "templatePath": "MindTouch/IDF3/Views/Article_directory",
    "templateTitle": "Article directory"
    "guid": "6232706f-1cf3-cc22-fd6e-195e013abab5",
    "templatePath": "MindTouch/IDF3/Views/Tag_directory",
    "templateTitle": "Tag directory"
►  Context IDs
Context IDs are stored in the contextswithmaps.csv file. Only translate Description content. (In the example below, only the text "Add file attachments to a page." should be translated.)
addfiles,Add file attachments to a page.,en-us,MindTouch_Guide/Manage_content.
►  Query recommendations
Query recommendations (or search recommendations) are stored in the file queryrecommendations.csvOnly translate Terms and Title content. (In the example below, only the text "editor how to use", "using the editor", "a add user", "add users" and "articles" should be translated.)
editor how to use,using the editor,Quick_Start_Guide/The_MindTouch_editor
a add user,,MindTouch_Guide/Manage_users_&_groups/Add_users
add users,,MindTouch_Guide/Manage_users_&_groups/Add_users
►  Learning paths
Learning paths are stored in the file learningpaths.csvOnly translate Title , Summary and Category content.
learn_search,All about search,Help your users self-serve through search:,Search
learning_path_experience,Create a learning path experience,Follow our step-by-step process.,Learning paths
create_text_templates,Create text templates,Create content templates you can call in the text editor.,Templates

important note   There is another learning path file, titled learningpathpages.csvDo not update this file!

  • Was this article helpful?