Translation Guidelines
- Applies to:
- All MindTouch Versions
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:
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 translationstat 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.