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. Each table is labeled with the Document ID and Data Type (these fields must not be edited) and contains 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:

• Id: Translation unit ID; this field must not be edited
   
• Source (language code): Source text extracted from Developer content, labeled with the appropriate XML/HTML language code
   
• Translation (language code): Placeholder for translated text, labeled with the appropriate XML/HTML language code
   
• Notes: Field available for notes about the translation, if necessary; added after export
   
• System Data: Processing information needed for translation unit, such as image properties; this field must not be edited

The source, translation, 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 translation 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 translation 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 translation 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 translation columns in the localization file. However, an understanding of the surrounding system information can be helpful in providing context for the text to be translated, if needed. Therefore, a detailed explanation of the translation unit IDs appearing in Developer-generated Microsoft Word localization files is provided here for reference.

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.

For module, section, user-defined question, assessment and package documents (Data Type = plaintext), the only text exported for translation is the document name. Each of these types of documents corresponds to a single translation unit containing just the unformatted document name. Therefore, the only translation unit ID possible for module, section, and package documents is:

• TXT_Title = document name

For glossary documents (Data Type = plaintext), in addition to the document name, each term and each definition link tooltip is also exported as a separate translation unit. Therefore, the number of translation units created for a glossary document equals the number of terms plus the number of tooltips plus 1. These translation units also consist of unformatted text. The translation unit IDs possible for glossary documents are:

• TXT_Title = document name
   
• GLEm.trm, where m is a unique integer = glossary term
   
• ILn.tt, where n is a unique integer = glossary link tooltip

For question documents (Data Type = plaintext), the text that is exported depends on the question type. All question types have a document name. All question types, with exception of User-Defined, contain Remediation Text and Question Text that are each exported as translation units. Multiple Choice (Many Answers & Single Answer) and Matching questions have Option text for each answer option. Each Option text is exported as a translation unit. Fill In questions have Blank Answer text that is exported as a translation unit. All question translation units consist of unformatted text. The translation unit IDs possible for question documents are:

• TXT_Title = document name
   
• QuestionText = text that asks a question
   
• RemediationText = text that provides remedial information
   
• BlankAnswer = text entered in the blank field on a Fill In question
   
• Option# = possible answer choice on Multiple Choice and Matching questions

Each web page document (Data Type = xhtml) 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. Therefore, the translation unit IDs possible for web page documents are:

• TXT_Title = document name
   
• H_Body = web page body text
   
• I_m_E, where m is a unique integer = image inserted in web page

As for the other types of documents, the translation unit for the web page name contains only unformatted text. However, unlike the preceding document types, web pages can include such elements as formatted text, images, and hyperlinks. In addition to translating the text, you must also address these aspects of web page translation units.

If the source web page contains text and/or paragraph formatting (such as bold, italics, bulleted lists, 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 Web Page Editor, as all other formatting will be removed upon import. 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.

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, as mentioned above, a separate translation unit is created for the image itself. The translatable text in this translation unit is the alternative text of the image, if assigned. Even if there is no source alternative text, you can add text to the Translation column that will be 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.

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 (Data Type = xml) 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. Specifically, each of the following components of a topic, if present, corresponds to an individual translation unit:

• Document name
   
• Custom bubble text (one or more translation units per topic frame, depending on play mode and output markup)
   
• Object name
   
• Decision frame header
   
• Decision path name
   
• Jump-in point
   
• Frame link tooltip
   
• Implicit text
   
• String input text
   
• Topic properties, including each System Process Document, Instructor Manual, Job Aid, and Test Document field; Keywords; and Roles

Except for custom bubble text, all of the other topic translation units contain unformatted text. They correspond to the translation unit IDs listed below. In examining this list, note that many translation unit IDs consist of prefixes and suffixes, where the prefix represents the general category and the suffix describes the specific type of text. Prefixes include A for action, BUB for bubble text, F for frame, IL for frame link, and TXT for plain text. Suffixes (such as on and tt) are detailed below in terms of the specific translation units to which they apply.

• TXT_Title = document name
   
• BUB_m.txt_[DP_CP_AP_DD_CD_AD], where m is an integer and the portion in brackets varies depending on mode and output markup = custom bubble text (see further detail below)
   
  (the integers m in multiple translation units for text from the same bubble always match)
   
• An.on, where n is a unique integer = object name
   
• Fq.dhl, where q is a unique integer = decision frame header
   
• Ar.dt, where r is a unique integer = decision path name
   
• Fs.jip, where s is a unique integer = jump-in point
   
• ILt.tt, where t is a unique integer = frame link tooltip
   
• Au.iit, where u is a unique integer = implicit text (for string input action)
   
• TXTv, where v is a unique integer = input text (for string input action)

The remaining translation unit IDs are all for topic properties, as assigned using the Properties toolpane.

• TXTw, where w is a unique integer = role
   
• TXTx, where x is a unique integer = keyword
   
• bpddep = System Process Document Department property
   
• bpdver = System Process Document Revision property
   
• bpdlcb = System Process Document Last changed by property
   
• bpdst = System Process Document Status property
   
• bpdtr = System Process Document Trigger property
   
• BPDRFy.n, where y is an integer = System Process Document Required fields property Required Fields field
   
• BPDRFy.c, where y is an integer = System Process Document Required fields property Comments field
   
  (the integers in the translation units for an n/c pair always match)
   
• BPDOUTz.r, where z is an integer = System Process Document Output property Result field
   
• BPDOUTz.c, where z is an integer = System Process Document Output property Comments field
   
  (the integers in the translation units for an r/c pair always match)
   
• bpdai = System Process Document Additional information property
   
• imnot = Instructor Manual Instructor notes property
   
• javer = Job Aid Revision property
   
• tdver = Test Document Revision property
   
• tdpps = Test Document Purpose of test property
   
• tdest = Test Document Estimated time property
   
• tdstp = Test Document Test setup property
   
• tdav = Test Document Additional validation property

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/or 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 will be 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/or Know It modes) and output (visible in Player and/or 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. In the generic example of a bubble text translation unit listed above,
BUB_m.txt_[DP_CP_AP_DD_CD_AD], it is the portion in brackets that specifies mode and output markup. Specifically, in each pair of letters, the first letter indicates the play mode and the second indicates the output. The codes for play mode are:

• D = See It/Try It mode
   
• C = Do It mode
   
• A = Know It mode

The codes for output are:

• P = Player
   
• D = Print (document) output

For example, the translation unit ID BUB24.txt_DP_CP_DD_CD corresponds to text that appears in only See It/Try It and Do It mode in both outputs, whereas the translation unit ID BUB32.txt_DP_AP corresponds to text that appears in See It/Try It and Know It modes but only in Player outputs.

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/or 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.

For example, consider the bubble containing the text "This text is valid in all modes. All of the text is valid in both outputs. This text is valid only in Know It? mode." In the Topic Editor, the first two sentences are marked to appear in all play modes, whereas the third sentence is marked to appear only in Know It mode; all of the text is marked for both Player and print outputs. When this topic is exported for localization, two translation units are created for this bubble: One contains the text "This text is valid in all modes. All of the text is valid in both outputs."; it has a translation unit ID of the form BUB15.txt_DP_CP_DD_CD. The second contains the text "This text is valid in all modes. All of the text is valid in both outputs. This text is valid only in Know It? mode."; it has a translation unit ID of the form BUB15.txt_AP_AD. If the output markup of any of the bubble text had also differed (for example, if the second sentence had been marked for print only), these translation units would have been divided further to reflect these differences.

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/or output markup. Upon import, these translation units will be 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 will appear 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 body 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/or 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.

Note: If you localize your content using Microsoft Word, the maximum number of documents that can be imported from a single localization file is 65,535. If you need to process more documents than this, you have a variety of options. You can export the documents in multiple batches that stay below the 65,535 limit. You can export all of your documents into one Microsoft Word file and then copy the extra tables beyond this limit to a new Word file that you import separately. Finally, you can change the limit on the number of tables processed during import of a Microsoft Word localization file. You do this by modifying the tableIndex parameter in the RunMe macro in the wordtoxliff.dot file in the installation folder. Specifically, edit the line

While (tableProcessed < ActiveDocument.Bookmarks.Count / 5 And tableIndex < 65535)

and replace the value 65535 with the maximum number of documents you plan to process at one time.