Translation Guidelines

Last updated
Save as PDF

Applies to:: All MindTouch Versions

Information about language codes, file formats, and content best practices when managing content exported from your Expert site with a TMS (Translation Management System) or LSP (Language Service Provider).

Language codes

Expert uses a 5-character ISO-639 language code that includes language and region, such as:

en-us (English, United States)
fr-fr (French, France)
fr-ca (French, Canada)
de-de (German, Germany)

Translation workflow

Page classifications can be leveraged to identify transitional states in a translation workflow between Expert and downstream systems such as a TMS.

Files and package structure

An Expert content export archive includes different file formats, such as html, png, json, csv, dat, css, mtarc, xml, and other associated files. To ensure data integrity, do not translate or modify dat, css, mtarc, and xml files.

Archive File Type	Filename	Translatable?
Manifest	package.xml	X
Site Structure	hierarchy.dat	X
Groups	groups.dat	X
Templates	page.html	✔
Content (pages, tags, attachments, page properties, file properties)	page.html	✔
Permissions	security.dat	X
Guide Tabs	guideTabs.json	✔
Content IDs	contextswithmaps.csv	✔
Search Recommendations	queryrecommendations.csv	✔
Paths	learningpathpages.csv	X
	learningpaths.csv	✔

The page hierarchy is referenced in the content export archive package.xml file.

Modifications to the hierarchy in package.xml, additions of new pages, or deletions of existing pages may cause an error in the import process. Do not delete or add pages in the content export archive.

When unzipping the content export archive for translation, there are two compression tools that are recommended:

For Mac: Decompressor
For Windows: 7-zip

When compressing the content import archive, make sure to include the original file directory structure:

translation-archive-zip-files

Do not compress the parent folder or your archive will not import successfully.

Page content

The following section(s) makes reference to three different methods to reference pages in an Expert site: the page id, URL path, and guid.

HTML structure and analysis

Exported page source content includes the same page source content visible in the Expert in-page editor, but includes HTML attributes and elements that are normally not found in page source content. In addition to the page source content itself, the page title, summary, tags, and classifications are also included in exported page source content. The mt-export-translate attribute is added to any HTML element that informs a TMS (Translation Management System) or LSP (Language Service Provider) whether the inner content (HTML text nodes) should or should not be translated. If the attribute is not set, it is presumed that the TMS or LSP will translate the inner content. Some content is analyzed for structure errors or rewritten in order to make it portable for import into a different Expert site.

Expert does not support changes made to non-translatable content. To maintain the integrity of the Expert site and to ensure Expert can support translated content, do not translate any content with an mt-export-translate=”no” attribute.

Page head and title

The title HTML element includes an mt-export-translate=”no” attribute. The remaining elements in the head HTML element are Expert metadata and should not be translated.

<head>
    <title mt-export-translate="no">Constructing a Sign-in Link</title>
    <meta name="mt-name" value="value"></meta>
</head>

H1 heading

A page title should only be changed by translated the h1 heading in the HTML body element. Do not modify the "mt-export-title" class.

<h1 class="mt-export-title">My Page</h1>

Content code blocks

DekiScript, CSS, and JavaScript code blocks that are interpreted and executed when page content is viewed include an mt-export-translate=”no” attribute. This does not include syntax highlighted code blocks for source code examples in languages such as DekiScript, CSS, JavaScript, PHP, C#, and Java.

<!-- DekiScript to execute when page content is rendered -->
<pre class="script" mt-export-translate="no">
    template('MindTouch/Controls/PageOverview');
</pre>
 
<!-- DekiScript source code example -->
<pre function="syntax.dekiscript">
    <a href=(site.homepage.uri .. '@app/auth/{id}/login?returnto=' .. uri.encode(page.uri))>"Sign in"</a>;
</pre>
 
<!-- PHP source code example -->
<pre function="syntax.php">
    echo "Hello!"
</pre>

Content inside any code block, whether it be for execution when viewing page content or for syntax highlighting source code examples, is never analyzed during page content export. Practically, this means that any included URLs that include locally scoped resource ids (such as page ids or file ids) will likely no longer resolve when the content is imported into a different Expert site.

Inline DekiScript

Inline DekiScript code (in double curly brackets) should not be translated.

{{ if(user.anonymous) { "Hello Stranger!"; } }}

Page tags and classifications

Exported page tags and classifications include an mt-export-translate=”no” attribute.

<p class="template:tag-insert">
    <strong>Page tags: </strong>
    <a mt-export-translate="no">API Endpoint</a>
    <a mt-export-translate="no">DekiScript</a>
    <a mt-export-translate="no">article:topic</a>
    <a mt-export-translate="no">version:all</a>
    <a mt-export-translate="no">pro-member-role:admin</a>
</p>

Translation status classifications

Site administrators can use the classification translationstatus to specify which HTML files should or should not be translated. We recommend the following options:

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

Special instructions must be provided to downstream content translators (TMS, LSP) in order to leverage these classifications as part of a translation workflow.

Conditional content

Conditional content inside p HTML elements can be safely translated. Do not modify any div HTML element attributes.

<!-- do not modify or translate div attributes -->
<div class="mt-style-conditional style-wrap" if="user.anonymous">

    <!-- content inside paragraphs are safe to translate -->
    <p>Conditional content!</p>
</div>

If conditional content references a specific user id in order to show or hide content, it will likely not be portable to a different Expert site. Individual Expert users are not exported when creating a content export job. If usernames are identical across different Expert sites, through the use of federated Single Sign-On, it is possible that username specific conditional content is portable, but this outcome is not guaranteed. In general, conditional content specific to unique, individual user attributes such as names is not considered a best practice.

Inline editor comments

Inline Editor comments do not include an mt-export-translate=”no” attribute and are expected to be translated.

<div class="comment">
    <div class="mt-comment-meta">
        <div class="mt-comment-author">Jane Smith</div>
        <time class="mt-comment-datetime" datetime="2019-11-05T23:28:07.799Z">Oct 31, 2019, 3:28 PM</time>
    </div>
    <div class="mt-comment-content">
        <p>This is a comment left in the page by an author</p>
    </div>
</div>
<p class="mt-script-comment">This is a comment describing the template call immediately below</p>
<pre class="script" mt-export-translate="no">template('MindTouch/Controls/PageOverview');</pre>

Page links and URLs

Page links include a URL and title attribute for each page.

<a href="https://example.com/foo" title="bar">Page Link</a>

Whether the URL and title attribute are identical or not, do not translate URLs. Maintaining the URL structure is crucial for auto-relating multilingual content. The following example demonstrates how a page URL and title attribute should look before and after a translation:

	Before translation	After translation
URL	https://example.com/security/product/get_started	https://example.comsecurity/product/get_started
Title Attribute	Get started	Introducción

Image and file attachment links

File attachments (including images embedded in page content as <img src="{src}" /> HTML elements) are stored in an Expert site as resources attached to a page.

Links to Expert site images and attachments in page content, provided they are not included inside a content code block, are converted to a portable format (removing references to any locally scoped identifiers) so that they can resolve correctly when imported into a destination Expert site. This includes all references to attachments on the page or attachments stored on any other page on the Expert site. Links to images and files external to the Expert site are not converted.

<img alt="foo.png" class="internal" src.path="//bar/baz" src.filename="foo.png" src="./foo.png" />

Downloading and Referencing Images and Files

When attached to a page, a file attachment is assigned an id value, which allows it to be referenced or downloaded from the API, without knowledge of the page location where it is attached. If the page id, URL path, or guid value is known, the file can instead be referenced from the API by using one of these values and a filename. Since page ids and file ids are locally scoped to a single Expert site, file URLs that include these values are not portable to other Expert sites. However, file URLs that include a page guid and a filename generally are portable, providing the filename is persistent and unchanging.

As explained in Content Code Blocks, during the context export process, file and page URLs located inside any content code blocks such as CSS, DekiScript, or JavaScript are not analyzed and rewritten to be portable, therefore a portable file URL format must be used if the content code block is intended to be imported into multiple Expert sites.

Get a File by Id (Not multi-site portable)

https://{hostname}/@api/deki/files/{fileid}

Get a File by Page Id and Filename (Not multi-site portable)

https://{hostname}/@api/deki/pages/{pageid}/files/={filename}

Get a File by Page URL Path and Filename

https://{hostname}/@api/deki/pages/={path}/files/={filename}

File URLs by page URL path and filename can be unstable if a page is moved and the redirect to it is later removed by creating a new page in the redirect source location.

Get a file by page guid and filename

https://{hostname}/@api/deki/pages/:{guid}/files/={filename}

Guide tabs

Guide tabs are found in the guidetabs.json file. Only translate templateTitle content. In the following example, 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"
  }
]

Content IDs

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

ContextId,Description,Language,PageTitle
addfiles,Add file attachments to a page.,en-us,MindTouch_Guide/Manage_content.
addnewpage,,en-us,
adminguide,,en-us,
advancedbranding,,en-us,
advsearch,,en-us,Success_Center_notices/002_January_2016/

Search Recommendations

Search Recommendations are stored in the file queryrecommendations.csv. Only 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.

Terms,Title,PageTitle
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
articles,,MindTouch_Guide/Manage_content./Best_Practice:_Identify_Articles

Paths

Expert Paths are stored in the file learningpaths.csv. Only translate Title, Summary, and Category content. There is a second Expert Path file, learningpathpages.csv, that should not be modified.

Name,Title,Summary,Category
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

Importing and exporting files

Between Expert source and destination sites, pages maintain a globally scoped guid that allows synchronization of page title renames, moves, and similar operations. File attachments do not have such a relationship and as a result, have cross-site behavior that differs from pages.

Exporting a page with a link to a file attached on the page

In this example, Site A contains a page with an img HTML element referencing the xyxxy.png file, attached to the same page. When exported to a new destination Site B, the resulting page shares the same guid, and the file appears the same in the page content.

The file is renamed on Site A and the img HTML element reference is updated on the page. The page is again exported and imported into Site B, replacing the img HTML element reference and attaching the renamed file as a new attachment. Since no shared guid exists between the original files, the destination site interprets the new filename as an entirely new file. As a result, two files are now attached to the page on the destination site.

Renaming a destination site file attachment

In this example, Site A contains a page with an img HTML element referencing the xyxxy.png file, attached to the page. The same page on Site B has since replaced xyxxy.png with corge.png.

If the page is again exported and imported into Site B, the changes on Site B will be overwritten as neither site understands that corge.png was intended to replace xyzzy.png on Site B.

It is recommended to never rename filenames on the destination site in order to keep page content img references to them in sync. If a different file is desired on the destination site, it can be replaced with a file of the same name. Rather than using the filename as a description, file attachment descriptions can be used to explain the use case for the replaced file.

Page with a link to a file attached on a different page

A common approach to centralized file attachment management is to assign one page (referred to as a Media Repository or Media Library) that all common files will be attached to. Since a media repository is a page, the rules dictating file attachment renaming and replacing across multiple sites generally apply.

References to a media repository file attachment in page content need to be preserved in both the source site and destination site. If a file attachment needs to be replaced in the destination site media repository, it should not be renamed.