CA Productivity Accelerator 12.1 and Later Localize Content Localize Content Once you have created content in one language, you might want to translate it into one or more different languages. The Developer provides functionality that facilitates this aspect of the localization process. Localization requires two main tasks; translating the textual content and re-recording the topics in the localized version of the target application. Text translation is usually handled by exporting the content to an XLIFF or Microsoft Word format, and sending the exported content to a localization company for translation. Topic re-recording is usually done in-house by authors or editors with Developer recording experience. This Developer localization flow involves six main steps: 1. Create a duplicate of the existing content to be translated. When duplicating, enable the option to also duplicate the glossaries. 2. Use the Localization process to export the content to an XLIFF or DOCX (Microsoft Word) translation package, depending on the requirements of your localization company. 3. Using the XLIFF or DOCX output, translate custom Developer text, including custom bubble text, web page text, link tooltips and alternative text, glossary terms, questions, and roles 4. Use the Localization process to import the translated XLIFF or DOCX files back into the Library, creating content outlines for each language. 5. Re-record each topic to update screenshots, actions, and object names and apply the appropriate template for the target language to update template text. This task can be performed while the content is out for translation. Note: The Localization import also sets the language property for the imported documents to the target language if you choose to overwrite the existing content. 6. Translate external content, such as package files and graphics, and relink these documents to the translated Developer content, if necessary; update glossary links.
Create a Duplicate To begin the localization process, you must first create a duplicate of the content to be translated. You do this using the Copy command and the Duplicate (selection and related) option of the Paste Special command. This creates new copies of the entire selection and all related documents and updates the links so that the new parent documents link to the new child documents. The resulting documents serve as placeholders that are overwritten with the translated content. Therefore, you need to create one duplicate of the original content for each language into which you plan to translate. For example, to translate English content into French, German, and Japanese, you need to create three separate duplicates of the original content. Note the following when creating a duplicate of the content. When duplicating content, you can choose to include or not include duplicate copies of the glossaries and style sheets linked to the selected content. Glossaries: It is important to select the Duplicate Glossaries option to include glossaries for translation and break the link to the original glossary. The default setting for glossaries is to create a duplicate. Style sheets: If you leave the Duplicate Style Sheets option unchecked, the duplicated content links to the style sheets linked to the original source content; allowing you to maintain a master style sheet for all related content. You can create language styles variations in the master style sheet if you need to use another font to display the text correctly in the localized language. There is no limitation to the number of language styles that you can add to a style sheet. If you prefer to have separate style sheets for each language, you can create a duplicate when you duplicate the content. The default setting for style sheets is not to create a duplicate, with the purpose of linking all content to a single style sheet. Note: A warning appears during export when you have multiple style sheets with the same name linked to the exported content. For simplicity in managing translations, especially those involving multiple languages, it is recommended that you create the duplicate for each target language in a separate, clearly identified Library folder. For the example above, if the English content were an outline titled "Document Basics" stored in a folder of the same name, you might create the folders "Document Basics - FR", "Document Basics - DE", and "Document Basics - JA" and paste one duplicate outline into each folder. Re-record Topics A crucial aspect of localizing content is capturing the screenshots and actions of each topic in the target language. To do this, you can use the re-record option in the Topic Editor, which allows you to easily re-create the same series of actions in the new language using the original topic as a guide. You must also update the template bubble text in the topic by selecting the appropriate template for the target language from the Properties toolpane. This provides a localized version of the automatically generated text portions of a topic. Note: The Developer provides a standard set of Default and Microsoft templates for all supported languages. Therefore, you do not need to translate template text unless you use a custom template or translate your content into an unsupported language. Copyright 2016 CA. All rights reserved. 2
Translate Custom Text In addition to recorded topic steps, your content may also include custom text, such as bubble text, modules and sections titles for organizational headings, questions, attachment tooltips, and web pages to provide additional information. The text you produce while modifying your content in this way must also be translated for localization. The Developer provides a Localization export and import flow to assist in the translation of this custom text. You can export this custom text in Word (DOCX) format for manual translation or XLIFF format for use in professional translation software that supports this format. The export results in a single file that contains a listing of all custom text in the source language that needs to be translated, divided into individual translation units, along with processing information required to ensure that each unit of text is imported correctly. During translation, you add translated text to the Word or XLIFF file so that the file includes the translated text in the target language in parallel with the original source text. After completing the translation, you then import the modified file back into the Developer, using the Import Localization command. During import, the documents that were originally exported in the source language are overwritten with the translated text provided in the Word or XLIFF file, and the Language property of these documents is updated to match the target language. Warning! Because the import process overwrites the text in the original documents, you MUST make a duplicate of the content to be translated before exporting it for localization; otherwise, you overwrite the content in the original source language. For a detailed discussion of this process, see Export Content for Localization and Import Localized Content. Translate External Content and Update Glossary Links The third type of content to translate is external material such as package and URL attachments. For example, you might link to an Excel spreadsheet or an external web site from a topic frame, or you might include an embedded graphic in a web page. Such external content is not included in the Localization export/import flow and must be translated separately. After translating such package files, graphics, and so on, you might need to update links in your translated content to ensure that they point to the appropriate targets. For example, if you translate the name of a file in a package, you must ensure that all links in the translated content are updated to reflect the new package file name. Tip: Renaming a package does not break the link to content; renaming linked package items does break the link. To avoid having to update links to package files in translated content, you should apply a language-neutral naming convention for package items and only change the name of the package itself. You can then differentiate package files of the same name based on the name of the package in which they are contained, which can be translated without breaking any links. After all text in your content has been translated, you should update glossary links in the translated documents. Because glossary documents are included in the duplication process and the Localization export/import flow, the appropriate glossary, including translated terms and tooltips and updated definition links, are already be assigned to each translated document. However, the links themselves are not preserved during the localization process so as to allow flexibility in the treatment of glossaries. Note that, aside from glossary links, the only links that might need to be updated in the translated content are those to package files, which are identified, in part, by file name. For other document types, which are identified solely on the basis of Document ID, links are updated automatically when you duplicate the selected content and related documents. Therefore, as stated above, duplication should always be the first step in the localization process. Copyright 2016 CA. All rights reserved. 3
Multi-user Considerations You can use the State workflow property as a means of tracking the various stages of a localization project. For example, you could create State values that identify the typical events that occur such as Released for Translation, Sent to Translation, Translation Review, Translation Complete, and so on. Export Content for Localization The purpose of exporting documents for localization is to extract the text added while customizing your content in a format that makes it convenient for translation. Before exporting any documents for localization, you must create a duplicate of the complete set of related documents, including the glossaries, to be translated. The duplicated documents serve as placeholders for the translated content; therefore, one set of duplicates must be created for each target language. It is recommended that you create the duplicate for each target language in a separate, clearly identified Library folder. After creating the duplicate, you can export it for localization from either the Library or the Outline Editor. If you create the duplicate in a separate folder as recommended, you can simply select the folder itself from the Library. Alternatively, you can select one or more individual documents. Tip: You can select multiple documents using the standard Windows selection keys (CTRL+click and SHIFT+click). After selecting content and initiating the export process, your next step is to set the export options. Save Location and File Format The first option is the location in which to save the localization file. The default location is the My Localization subfolder of the My Documents folder on your local hard drive, but you can choose any other location on your computer or server for which you have Write permissions. You must also specify a name for the localization file. This file name does not in any way affect the processing or translation of the documents it contains, but it is recommended that you use a meaningful name that reflects the intended translation process. For example, you might use the name Document Basics_EN_HU for content to be translated from English into Hungarian. Also note that certain reserved characters are not permitted in localization file names. In addition to specifying the file name, you also must select the translation file format as either Microsoft Word or XLIFF. In both cases, the same text components of the selected documents are exported; the difference is in the intended translation process. ** Exporting to Microsoft Word format (file extension DOCX) provides an easily readable listing of text that is amenable to manual translation. The problem is that there can be macros that do not work properly with translation. Potential failure when using more than 10 topics is possible. Exporting to XLIFF format (file extension xlf) provides an XML-based file for use with translation tools that support this format. Using XLIFF is highly recommended and the use of Microsoft Word is discouraged** Content Selection The second option allows you to export your selection only or your selection and all related documents. In general, documents linked as children of the documents in your selection are included as related, whereas those linked as parents are not. Any glossary assigned to one or more documents in the selection is also included as a related document. Click the View related documents link to display a list of all documents related to your selection. Note: The content of a package document is not exported for localization. Copyright 2016 CA. All rights reserved. 4
Language The third option is to specify the source and target languages. The source language is determined by the Developer and reflects the Language property of the selected document(s). The target language is the language into which the content is being translated. Note that only one target language can be selected. If the same content is intended for translation into multiple languages, this content must be duplicated multiple times, and each set of duplicated content must be exported separately with the appropriate target language specified. During the Localization export process, the Developer extracts the custom Developer text included in the selected document(s) and writes it to a single localization file of the selected format (XLIFF is recommended). Included with the text is some required processing information, such as document and translation unit IDs, that is essential for the text to be imported successfully after translation and must not be changed. The custom Developer text that is exported for localization depends on the document type as follows: Module - Roles - Keywords - Description Section - Roles - Keywords - Description Topic - Roles - Keywords - Custom bubble text, including formatting and markup for play modes and Player and document outputs (one or more translation units per topic frame, depending on play mode and output markup) - String input text - Implicit text (for string input action) - Object names - Jump-in points - Decision frame header and Decision path names - Frame link tooltips - Frame comments (Expected Results, Author Notes, Instructor Notes) - Topic properties (Properties toolpane fields for Instructor Manual, Job Aid, System Process Document, and Test Document). Package Web Page - Body text, including formatting. Note that the body text is segmented. - Images (advisory title and alternative text) - Tables (cell contents, caption, and summary) - Links (tooltip) Copyright 2016 CA. All rights reserved. 5
Assessment - Roles Question - Roles - Remediation text - Question text - Blank Answer text - Option text Glossary - Glossary terms - Tooltips for glossary terms A summary message appears if some of the documents you selected could not be processed. Clicking the View activity log link in the message displays a list of the results for each document. The export creates either an XLIFF or DOCX file depending on your format selection. Selecting Cancel during the export for localization process displays a message with a link to a list of the documents that have already been exported. Although the partial localization file can be edited and imported, it includes only a subset of the documents intended for translation. Therefore, it is recommended that you delete the partial localization file and restart the process from the beginning. Note: In this version of the Developer, the Web Page Editor creates web pages with a different underlying structure than those web pages created with previous versions of the Web Page Editor (legacy web pages). However, during the export for localization, the Developer converts old web pages to the new structure. This structure change affects the existing translation memory (TM) for localized content created with previous versions of the Developer. Multi-user Considerations In a multi-user environment, when you are online, you also have the option to choose local or server content. Local content includes the locally edited copies of all selected documents that you have checked out and the server versions of those not checked out to you. Use this option for documents in progress for review. Server content includes only the checked in versions of the selected documents. Any local changes to checked out documents are ignored. Use this option for final versions of documents. You can also export while offline, but to do so, you must have the documents in your local cache. Nevertheless, it is recommended that you check in all documents to be exported for localization and export the server content to ensure that you include the most up-to-date versions. To export content for localization: 1. From the Library or Outline Editor, select the folder(s) and document(s) you want to export for localization. You can select multiple documents using the standard Windows selection keys (CTRL+click and SHIFT+click). 2. On the Tools menu, point to Export and choose Localization. 3. Set the export options. 4. Click OK. The Developer processes the selected documents, creating a single file containing all extractable text, and associated processing information, in the specified location. If any errors occur, they are written to an activity log, and a Partial Export message box appears. You can click the View activity log link to view the results of the export or click OK to close the message box. Copyright 2016 CA. All rights reserved. 6
Import Localized Content After editing the exported localization file to include translated text, you use the Localization import command to add the translated content to your Library. This process overwrites the text in the set of duplicate documents that you exported for localization with the translations contained in the imported file. When importing for localization, you should select a XLIFF localization file. The Developer reads the selected import file and identifies the documents to be replaced according to the Document IDs recorded during export. The replacement of source text by translated text within a document is then based on the translation unit IDs contained in the localization file. If no translation is provided for a particular translation unit, the source text is left unchanged. Warning! You cannot import localized content into documents that are open in the Developer. You should close the outline, and all documents related to the content that you are importing, before starting the localization import process. At the conclusion of the import, a message informs you if translated content was not imported and the errors appear in the activity log. When the Developer imports the localized content, it checks to see if the duplicate content you used to create the export has been changed since the export; for example, you may have added additional text to a web page. If you overwrite your duplicated web page, you lose your new edits. You can use the Overwrite Documents that Have Changed Since Last Export option to either skip importing the changed documents or overwrite them. If you choose to leave the option unchecked, the import preserves the changes by not overwriting the source documents. After the import, you can check the activity log to see which documents were not imported. You can then create a separate export of those updated documents to send for translation. The option to overwrite the original duplicate affects document types in different ways. Web Pages: Imported web pages replace the web pages in the duplicate outline that you used to create the localization export; any changes made to the source content after the export are overwritten during the import. Note: Due to a change in the Web Page format, you cannot import content that was exported and translated using a previous version of the Developer. If you are upgrading versions, make sure that you import your content into the Library before upgrading. Topics: Frame screenshots in topics are not overwritten during the import; therefore, your re-recorded frames are preserved. Imported bubble text for a frame completely overwrites the existing text in the equivalent frame. Frames added to a topic during the re-record process are preserved, though you may need to localize custom text added to the frame. Questions: All question text is replaced with the imported, localized text. New question options added to multiple choice and matching questions are preserved, though you may need to localize the new text. Packages: Package files are not included in the content exported for localization and are not overwritten. Copyright 2016 CA. All rights reserved. 7
In addition to adding the translated text to the imported documents, the import process also updates the Language property of each document to the target language selected during export. If the language of a document has changed since it was exported, you are not prevented from continuing with the import process, but an informational message is added to the activity log. Tip: If the imported content includes topics for which role assignments were translated, you should update the master role list for the target language to include these roles. If no master role list exists for the target language, you should create a new master role list before importing the translated content. A summary message appears if some of the documents you selected could not be processed. Clicking the View activity log link in the message displays a list of the results for each document. Selecting Cancel during import stops processing after completion of the current document and displays a message with a link to a list of the documents that have already been imported. Click the View activity log link in the message to display a list of the results for each document. Multi-user Considerations For a document to be overwritten during import, it must be checked out. Therefore, before initiating the import process, you should ensure that any documents that must be overwritten are either checked out to you or checked in to the server. If you plan to import a localization file while offline, you must check out all such documents before going offline. However, if a document that needs to be overwritten is not checked out and you are online, the Developer automatically checks the document out to you and replaces it with the corresponding document from the localization file. If the document cannot be checked out, for example, if it is open in another editor or checked out to another user, it is skipped. At the end of the process, a summary message appears with a link to an activity log. Clicking the View activity log link in the message displays a list of the documents that were checked out to you during the process and those that could not be checked out. After you complete the import process, you should check in all affected documents to make them available to other authors and add the changes to the Developer's version control system. When you check in a translated document, its version number is incremented, reflecting the fact that its contents have changed. After updating the master role list, you should check it in. It is recommended that you always manually check out all documents to be overwritten during import, to ensure that all documents are processed during import of localized content. To import content for localization: Note: Close the content you are importing before starting the import process. 1. On the Tools menu, point to Import and choose Localization. 2. Click Browse and navigate to the translated file you want to import. 3. Select the translated file and click Open. Copyright 2016 CA. All rights reserved. 8
4. Leave the Overwrite documents that have changed since last export unchecked to skip source documents that have been changed since the localization export. Check the option to overwrite changed source documents with the localized versions. 5. Click OK. The Developer processes the selected file, replacing the text in the original documents with the translated copy. If any errors occur, they are written to an activity log, and a Partial Import message box appears. You can click the View activity log link to view the results of the import or click OK to close the message box. Localization using XLIFF XLIFF, or XML Localization Interchange File Format, is an XML-based format that was developed specifically for use in translation projects. As its name and origin suggest, XLIFF was designed to facilitate the exchange of information across different systems during document localization. In general, source text is converted into XLIFF by a filter that depends on the source structure. This filter extracts the translatable content as plain, unformatted text, allowing the translator to concentrate on the meaning of the text to be translated, regardless of the original source file format, structure, or appearance. Such additional information about the source is still preserved in the XLIFF file in the form of tags, which are used to apply the appropriate processing to the translated text so that the original structure and formatting are reproduced upon conversion of the translated text back to the original format. It is assumed that, if you choose to localize your Developer content using XLIFF, you are already familiar with basic XLIFF concepts and are working with an XLIFF tool or sending your content to a localization vendor who does. For further information on XLIFF in general, see the web site of the OASIS Technical Committee on XLIFF at https://www.oasis-open.org/committees/tc_home.php?wg_abbrev=xliff Developer XLIFF Processing When you execute the Export Localization command, the Developer applies a filter to the selected content, extracting all translatable text and rendering it in a form that complies with XLIFF specifications. The text extracted depends on the type of document selected. Within the XLIFF file, the text is organized by document and then by translation unit within each document. Therefore, as you process the XLIFF file, you proceed sequentially through each of the exported documents. Warning! During the Localization export process, the Developer applies a unique ID to each translation unit that includes information regarding the document ID, document type, and text type (if the document can have multiple translation units; see below). Therefore, you should neither merge nor split translation units during processing in XLIFF, as this could lead to problems upon import. Specifically, if the file selected for import contains translation units with invalid IDs or other problems, the Developer skips such translation units, thus not importing the corresponding text. Web Pages Each web page document is exported as at least two translation units, one for the document name and multiple for the body of the web page, regardless of the amount of text it contains. Web pages can include such elements as formatted text, images, and hyperlinks. Although such information is not relevant to the translation of the text itself, it is important for ensuring that the translated document has the same structure and appearance as the source document. Therefore, the XLIFF generated by the Developer includes such information within web page translation units using the standard XLIFF processing tags <bpt> (begin paired tag) and <ept> (end paired tag). These tags surround appropriate pieces of text in the source translation unit and contain XHTML code (generated by the Web Page Editor) corresponding to the formatting and processing needed. Copyright 2016 CA. All rights reserved. 9
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. 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). 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. Despite the obvious overlap in content, these translation units should be translated and maintained as separate units because they represent different combinations of mode and output markup. 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. In addition, this approach simplifies the translation process. That is, translators are frequently comfortable with formatting attributes such as bold or font name, but might find it more difficult to interpret and appropriately process the mode and output markup, which are specific to the Developer. Moreover, use of a translation memory can minimize the impact of any duplication. Images and Hyperlinks For images (<img> tag) in web pages, the processing tags always include the image source attribute (src) and might also include attributes representing the properties that can be set using the Image Properties dialog box. Some of the attributes are alternative text (alt), size (style), border (border), and alignment (align). Likewise, for hyperlinks (<a>, or anchor, tag) in web pages, the processing tags always include the hyperlink target attribute (href) and might also include an attribute representing the tooltip (title). In general, image and hyperlink processing tags should also be copied from the source text to the corresponding portion of the translated text. However, you might want to translate the alternative text for an image or the tooltip for a hyperlink. You can do so by directly editing the corresponding <bpt> processing tag to include the appropriate translation in the alt or title attribute, respectively. Note that, except for URL images or URL hyperlinks, you should not need to edit the image source (img src) or hyperlink target (a href) 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). See Export Content for Localization for a list of the text that is exported for each document type. Summary In summary, the translation of custom Developer text using XLIFF 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 formatting and processing information in the form of <bpt>/<ept> processing tags. For the most part, these tags should be copied directly from the source text to the linguistically equivalent portion of the translated text. 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. A translation memory should prove helpful in automating translation in such cases. Copyright 2016 CA. All rights reserved. 10
Localization Using Microsoft Word ** Localization using Microsoft Word format (file extension DOCX) provides an easily readable listing of text that is amenable to manual translation. The problem is that there can be macros that do not work properly with translation. Potential failure when using more than 10 topics is possible. Exporting to XLIFF format (file extension xlf) provides an XML-based file for use with translation tools that support this format. Using XLIFF is highly recommended and the use of Microsoft Word is discouraged ** Copyright 2016 CA. All rights reserved. 11
Copyright 2016 CA. All rights reserved. 12