If you arel not using XLIFF-based translation tools, you should use the Microsoft Word option for localizing your content. Exporting to Microsoft Word provides an easily readable listing of text that is amenable to manual translation.
The same initial processing is applied to your content when you execute the Export Localization command, regardless of whether you choose to export to XLIFF or Microsoft Word. Specifically, the Developer applies a filter to the selected content, extracting all translatable text and creating a list of translation units, or logical segments of text, organized by document. The text extracted depends on the type of Developer document selected, as discussed later, but is the same for both XLIFF and Microsoft Word. In XLIFF, the translation units are presented as plain, unformatted text, with any necessary formatting or processing information managed through the use of processing tags. In contrast, in Microsoft Word, any formatting applied to the text in the Developer is directly reflected in the exported file, so that you can see how it actually appears in the source documents. You then replicate this formatting in the translated text using standard Microsoft Word formatting controls so that the translated content has the same appearance in the Developer upon import.
Localization File Structure
The localization file created upon export to Microsoft Word consists of a series of tables, one for each Developer document exported. The first table in the Word file specifies the hard-coded language codes for the Source and Target properties. The Source is the language of the original content and the Target is the language selected as the target when the content was exported. Each subsequent table is captioned with the Document ID and Data Type (these fields must not be edited), with the table containing all translatable text from the document, with one row for each translation unit. (The number of translation units depends on document type and contents, as explained further below.) The five columns in each table are as follows:
Note: In previous versions of the Developer, the codes for the source and target languages were hard-coded as column headings into each translation table.
The source, target, and possibly Notes columns are the primary focus for translation; the information in the remaining columns can help provide context for the text to be translated but is required for system processing and should not be changed.
Warning! Do not edit any system information contained in the exported localization file, including Document IDs, document data types, translation unit IDs, and System Data entries. Doing so can cause the import process to fail, either for the entire localization file or for any directly affected document(s). You should also not change layout attributes such as splitting tables, and so on.
Use of a Microsoft Word file for localization is straightforward: Simply translate each source translation unit in the source column and add the translated text to the appropriate table cell in the target column. If a particular translation unit, such as a technical term, does not need to be translated, you can copy the source text directly to the target column without modifying it or leave the table cell empty. If the source text is formatted (which might be the case only for bubble text and web page body translation units, as explained in detail below), you should apply the same formatting to the translated text so that it matches the appearance of the source. If desired, you can also use the Notes column for communication with the translator about the translation. For example, you might include the note "Do not translate" for a translation unit that should be kept in the source language. Likewise, a translator could include notes about particular translation units, such as questions about the translation of technical terms.
Upon import, the Developer processes each document and each translation unit in the localization file, overwriting the original source content with the text provided in the target column. If no translation is provided for a particular translation unit, the source text is left unchanged. The import and overwriting process is based solely on document and translation unit IDs; it is not affected by any changes that might have been made in the Developer content after it was exported or in the Source column text of the localization file. Any entries in the Notes column also do not affect the import process.
Translation Unit IDs
As mentioned above, you can localize your Developer content using Microsoft Word by considering only the source and target columns in the localization file.
Note: The same translation unit IDs and other system information are also included in Developer-generated XLIFF localization files. However, this information generally remains hidden during XLIFF processing because it is not exposed by most XLIFF translation tools.
Translation unit IDs depend on the function of the text within the document. As a result, each type of Developer document can correspond to only certain types of translation unit IDs. All documents include a TXT_Title translation unit ID with the unformatted document name. Other documents, such as modules, sections, and topic, may also include translation unit IDs for roles and keywords. Each web page document is exported as at least two translation units, one for the document name and one for the body of the web page, regardless of the amount of text it contains. If the web page contains one or more embedded image(s), one additional translation unit is created for each image. Web pages also include translation unit IDs for alternative text for images and summary text for tables.
Web Pages
If the source web page contains text and paragraph formatting, you should apply the same formatting to the translated text using Microsoft Word's formatting tools. However, you should use only the types of text formatting supported by the Web Page Editor, as all other formatting is removed upon import. The following web page formatting is preserved:
Paragraph alignment
Hyperlink
Images
Numbered and bulleted lists
Fonts
Bold, italic, underline
Strikethrough
Subscript, Superscript
Special characters
Page breaks
Cross-reference links
In addition, if the source web page has a background color, the cells corresponding to the Source and Translation of the web page body translation unit have the same background color. However, this color is provided for illustration only, simply to match the appearance of the source document. Changing this color does not change the background color of the translated web page document upon import into the Developer.
Tables
Each table cell is segmented and exported as its own translation unit. In addition, translation units are created for the table caption and table summary. The table summary is used to provide an accessible description of the table's contents.
Images in Web Pages
If an exported web page contains an image, a small placeholder graphic appears in the source web page body translation unit to indicate its position in the layout of the web page. You should copy this graphic to the same location in the layout of the translated web page to include the image in the translated web page upon import. In addition, a separate translation unit is created for the image itself. The translatable text in this translation unit, if assigned, is the alternative text of the image (for accessibility) and the advisory title that appears in a tooltip for mouse hovering. Even if there is no source alternative text, you can add text to the Translation column that is imported as the alternative text for the image in the translated web page. Image translation units also always contain an entry in the System Data column that specifies the source of the image, as well as other image properties (such as size, border, and alignment), if assigned. You should not edit any system data.
Hyperlinks in Web Pages
If an exported web page contains a hyperlink, the hyperlink also appears in the source translation unit for the web page body. Use the Microsoft Word controls for editing and inserting hyperlinks to create the same hyperlink in the corresponding location of the translation (from the equivalent text or the placeholder graphic, as appropriate). You should use exactly the same Address for the hyperlink target in the Edit Hyperlink dialog box for the two hyperlinks. However, you can translate the hyperlink tooltip, or add a tooltip for the translated web page even if none is provided in the source web page, by clicking the ScreenTip button in the Edit Hyperlink dialog box and editing the text as necessary.
Note that, except for URL images or URL hyperlinks, you should not need to edit the image source or hyperlink target attributes in web page translation units. Rather, these values are updated when you create a duplicate of your content (including related documents) before exporting it for localization. If you need to change these attributes further, you should edit the image properties or edit the hyperlink properties from the Web Page Editor after importing the translated web page.
Note: Hyperlinks are included in translation units only for manually created links, not for glossary links. Rather, you should update glossary links from the Developer after importing the translated content and glossary (or glossaries).
Topics
Topics can consist of a large number of translation units, and the translation units corresponding to bubble text can include both formatting and markup for play modes and outputs. See Export Content for Localization for a list of the topic components that correspond to individual translation units. Except for custom bubble text, all of the other topic translation units contain unformatted text.
The translation units for custom bubble text require additional explanation for two reasons: formatting and mode and output markup.
If the source bubble text contains text and paragraph formatting (such as bold, italics, paragraph alignment, and so on), you should apply the same formatting to the translated text using Microsoft Word's formatting tools. However, you should use only the types of text formatting supported by the Topic Editor, as all other formatting is removed upon import.
If exported bubble text contains a hyperlink, the hyperlink also appears in the source translation unit for the bubble text. Use the Microsoft Word controls for editing and inserting hyperlinks to create the same hyperlink from the corresponding text in the translation. You should use exactly the same Address for the hyperlink target in the Edit Hyperlink dialog box for the two hyperlinks.
Note that, except for URL hyperlinks, you should not need to edit the hyperlink target attributes in bubble text translation units. Rather, these values are updated when you create a duplicate of your content (including related documents) before exporting it for localization. If you need to change these attributes further, you should update the bubble text link from the Topic Editor after importing the translated topic.
Note: Hyperlinks are included in translation units only for manually created links, not for glossary links. Rather, you should update glossary links from the Developer after importing the translated content and glossary (or glossaries).
In addition to formatting and hyperlinks, custom bubble text can also include markup for play mode (visible in See It/Try It, Do It, and Know It modes) and output (visible in Player and print outputs). The ID of each custom bubble text translation unit indicates the mode(s) and output(s) in which the text is set to appear.
If all of the custom bubble text in a topic frame is marked for the same play modes and outputs, it is exported as a single translation unit. However, if the same bubble contains custom text marked for different modes and outputs, multiple translation units are generated, one for each unique set of play modes and outputs. In this case, the same integer appears after the prefix BUB in all translation units corresponding to the same bubble, but the mode and output codes differ as needed to reflect the text markup.
Despite the obvious overlap in content, these translation units should be translated and maintained as two separate units because they represent different combinations of mode and output markup. Upon import, these translation units are written to the same frame bubble, with the first marked to appear only in See It/Try It and Do It modes and the second marked to appear only in Know It mode. That is, where the original bubble text consisted of three sentences, the translated bubble text appears as five sentences overall, one set of two sentences from the first translation unit and another set of three sentences from the second translation unit. Although this approach leads to some duplicate translation and repetition in the bubble of text appearing in different markup combinations, it ensures that the play mode and output markup of the source text is accurately reproduced in the translated bubble text, so that the translated topic publishes correctly.
Summary
In summary, the translation of custom Developer text using Microsoft Word is relatively straightforward, with most translation units consisting simply of unformatted text. The exceptions are web page text and custom bubble text, which can include text and paragraph formatting and processing information such as hyperlinks. For the most part, this formatting should be exactly reproduced in the linguistically equivalent portion of the translated text. Any formatting present in the translated text that is not supported by the Developer is removed during import.
In addition, in cases where the mode and output markup of the text within a bubble differs, multiple translation units are created for a single bubble. Because the IDs of the resulting translation units contain information on markup, these translation units should always be processed individually, even if they contain similar text. This preserves the appropriate bubble text markup upon import of the translated content.