Tech Writer Today’s Technical Writing Tips and Tricks column is brought to you by Adobe Systems, Inc. Download a 30-day free trial of Adobe FrameMaker here.
Over the past few years, I’ve had to manage the translation into French of user guides and online help for TSX SecureFile. The documentation consists of PDF user’s and administrator’s guides produced using unstructured Adobe FrameMaker and web-based online help produced using Quadralay’s WebWorks ePublisher.
This article is based on a relatively simple scenario – a lone technical writer with a small number of manuals being translated into one language. I’m not going to discuss how to find a translator as that may be out of your control; your company may already have a translation service in place. But the tools the translation service has available are important to your success.
If you’re using Adobe FrameMaker, make sure that your translator can work with FrameMaker files in their native format, because conversion to Microsoft Word is not an option! In addition, you should make sure your translator can work with the same version of FrameMaker that you’re using.
Costs vary depending on the size of the translation project and the language or languages involved. You can expect to be charged a setup or administration fee as well as a per-word fee for the translation. Some translators also charge a formatting or desktop publishing fee (usually on a per-page basis), but I always tell them not to worry about formatting. Since French text is usually longer than English text, the translated files require some reformatting, but I do this myself.
Managing the expectations of your project managers is absolutely critical. Translation adds time and effort to any documentation project. In my case, I found that it typically added about ten days of effort and a month of elapsed time to the normal documentation cycle. So if you have to release both (or many) languages simultaneously, then you need to finish your English documentation earlier than you would if the documentation wasn’t being translated. You also need to allow time for a review of the translated files.
Setting Up the Files for Translation
When sending files to the translator, I use these FrameMaker settings.
- View Text Symbols: On
- Show/Hide conditional text: Show all conditional text and show condition indicators.
The translator should keep these settings; otherwise they risk deleting or overwriting markers or conditional text. The translator should also keep the same file names, otherwise cross-references that are set up with markers will break.
What Not to Translate
Not everything in a FrameMaker file needs to be translated. Since you’re paying by the word, it’s important to tell the translator what not to translate.
| Table of Contents | The TOC updates automatically once the headings in the document have been translated. |
| Headings in cross-references | The cross-reference format needs to be translated. For example “For more information, see …”. Do this only for the first chapter file, then import the translated format across all documents.Cross-references should update automatically once the heading to which the cross-reference points has been translated. |
| Markers | Do not translate text in any markers except for Index markers. |
| Index | The only thing in the Index document that needs to be translated is the Index heading. Like the Table of Contents, the index updates automatically once the index entries have been translated. |
Elements that Require Special Handling
Some things require special attention.
| Headings for Table of Contents and Index | Translate the headings for the Table of Contents and the Index (e.g., the word “Contents” and the word “Index”). Do not translate the table of contents or index, as these are automatically generated by FrameMaker. |
| Index Entries | The text of the index entry is inside an Index marker; for example: special handling:index. Index entries are to be translated. Be careful not to delete the colon or semicolons inside an index entry, as these are the delimiters that FrameMaker uses to determine index levels and to separate multiple index entries inside the same marker. Index entries are markers, so they won’t be visible unless View Text Symbols is on. |
| Conditional Text | FrameMaker uses conditional text to allow different text for different types of output. Generally, all text in conditionals should be translated, even if it appears to be a duplicate of other text. |
| Text Insets | Only the original text insets should be translated. Text insets that are referenced in the documentation should not be translated. You may need to flag these with a special conditional (for example, DoNotTranslate), or a comment in the file. |
Include any graphics or screen captures when you send your files off for translation. In my case, the development group managed the translation of the user interface separately from the documentation, so I was able to provide the translators with French screen captures. That may not always be the case, and even if it is, be prepared for questions from the translators about interface terminology.
When You Get the Translated Files Back
After receiving translated files, create an English copy in a separate directory. When I get the translated files back, I create a copy of the English book in a separate directory, then copy the French files over that version. This assumes that the file names are the same. I then check the files for problems like unresolved cross references and review the pagination and reformat as needed,
I use a similar procedure to create the online help. I create a copy of the WebWorks ePublisher project and copy the French files into it. I change to project’s locale to French, so that ePublisher’s interface elements and messages will appear in French.
Have translated files reviewed by a native speaker of the language. Don’t assume that just because the files look good in FrameMaker or ePublisher, that they’re correct.
As a lone technical writer, adding translation to the list of duties gives you more stuff to juggle. These tips should help you prepare for the production gotchas and help avoid delaying or derailing delivery.
Find more tips on using FrameMaker at the Adobe TCS Community Help Client or on using ePublisher at the WebWorks Wiki
