WritersUA - Training and Information for User Assistance Professionals

Ten Best Practices for Preparing a Flare (or RoboHelp) Project for Translation

By Lorraine Kupka

Bookmark and Share


Click a link below to jump to a particular section; click any "CONTENTS" image following a section heading to jump back here.

Introduction    Link to contents

With the growth of the global marketplace, the localization of products has increasingly become a key factor for businesses to maintain a competitive edge. When products are localized, product documentation must be also translated-everything from marketing collateral to instruction guides, to software application Help. As writers, it's important to understand how our writing impacts the translation process and localized products; and it's equally important to actively participate in the process, rather than participate as passive observers.

Getting your content ready for translation can seem like a daunting task, but following some simple guidelines can result in significant benefits, such as cost savings and customer satisfaction.

Although I am writing this article from the perspective that your source project is written in English and that you will be translating the source to various non-English languages, the guidelines I discuss apply regardless of the language your source content is written in.

My Experience    Link to contents

A client of mine recently contracted to have their web applications localized for several languages. This included the application Help that I created using MadCap Flare.

I passed the source Flare project (written in English) to the translations provider who extracted project components to be translated and used a Translation Memory database to store English words and phrases and their equivalent translations. After content was translated, the provider delivered one translated Flare project for each language, along with the generated output for each language.

As a result of this experience, I developed many best practices for preparing an English Flare project for translation.

Although my experience with translating topic-based projects is with Flare only, I believe these guidelines apply to any topic-based development tool; and many, if not most of them apply to any type of documentation product, not just to software documentation.

Some of these practices involve workflow and how translation is accomplished, so I'd like to provide a little background about the translations process.

Localization Scenarios    Link to contents

There are various means by which a product and accompanying documentation can be localized. You can:

Contract with a translations provider who will use a Translation Memory system.

Use an in-house translations department or staff member who will likely use a Translation Memory system.

Machine translation.

Your translations provider or in-house department might even translate the content with MadCap Lingo, which is integrated with Flare.

The amount and type of your involvement might vary and some of the best practices will not be applicable, depending on which of these scenario you follow.

Creation of a Term Base    Link to contents

No matter which scenario you use, the most likely first step will be that your translators will create a database of user interface terms for each language in which the documentation will be translated. You will need to provide the user interface terms in some form (either from application text strings or from a document that contains the terms referenced in your documentation). The term base will include each English term and its foreign language equivalent. The use of a term base will save translation costs if your documentation uses those terms consistently.

Why Are Best Practices Important?    Link to contents

Best practices for writing source content are important in order to create a translated product that meets your quality and usability standards. Customers who understand a product and how to use it will have increased satisfaction with that product, thereby increasing its marketability and the reputation of your company or your client's company.

For a simple comparison, think about the process of photocopying. If the original has defects, so will the copy. Translators can't be expected to compensate for poor design or poor writing.

Following guidelines makes the process of translating content go more smoothly, resulting in higher job satisfaction and potentially, lower cost.

That said, here are my ten best practices for preparing documentation for translation.

Ten Best Practices    Link to contents

Before sending your project to the translations provider, be sure to do the following:

1 - Follow Best Practices for Technical Writing    

The quality of the written word is probably one of the most important things to consider when you are preparing to localize a project. Make sure your writing is clear, concise, and consistent. Writing that is unclear or ambiguous will be harder for translators to understand and to translate.

It's not my intent to provide a comprehensive list of good writing practices here, but I consider these best practices to be most important.

  • Organize your content into a logical structure that makes is easy for a reader to understand.
  • Avoid long, run-on sentences with many modifying clauses. Instead, write short clear sentences that each express one thought. Translators must understand what you are trying to say to be able to translate it.
  • Avoid nominalizations, keep sentence structure parallel, and avoid misplaced modifiers.
  • Avoid slang expressions, jargon, and colloquialisms. They can be difficult to interpret and translate, plus they might offend people from other cultures. For example, avoid phrases such as "nuts and bolts," "off the record," and "piece of cake." Instead use the terms "basics," "confidentially," and "easy."
  • Make sure that verbs agree with their subjects and that pronouns agree with their antecedents.
  • Use terms and phrases consistently. Reusing terms instead of using synonyms simplifies translation because once a term is stored in a Translations Memory database, it can easily be recalled and reused.
  • Use active voice instead of passive voice as much as possible since it is easier for translators to understand who or what is performing the action.
  • Consistently apply style conventions.
  • Don't use the same word as both a noun and a verb (and especially not in the same sentence!) For many translators, English is a second language; they translate content into their native language. Why make the content potentially confusing and their job harder?
  • If you use symbols, make sure they are general and not specific to a particular culture.

2 - Consider How the Text Will Appear After Translation    

When designing and using styles, it's important to keep in mind that your decisions will affect the appearance of translated text. For example, it's best to minimize the use of bold or italics for emphasis because Asian characters can be difficult to read or even unreadable when bold or italics are applied. Translators would have to compensate by changing the font size or substituting a different font, but it's better to avoid using bold and italics completely. If you must emphasize text, use color or underlines.

When text is translated to non-English languages, it often takes up more space, so design your styles and topic elements to allow for text expansion. For example, in Flare when you create a table, select "AutoFit to contents" instead of "Fixed column width."

3 - Use CSS Styles Instead of Local Formatting    

Use CSS styles instead of local formatting (inline styles). This enables translators to change the appearance of text quickly and easily, if necessary to handle problems with bold, italics and text expansion. If a translator needs to resize a style, change a font, or apply color for emphasis, it's much faster and easier to change one style rather than to search for and change every occurrence of a particular format in multiple topics.

An added bonus is that your project's topics will be smaller; and if you work in code view (as I often do), your XHTML code will be easier to follow.

4 - Use Naming Conventions    

Adopt a convention for naming files, folders, and projects before translating content or handing the project over to the translators. These conventions will uniquely identify each translated Flare project and project output so there are no conflicts, between outputs, especially if the outputs are located on the same physical server or in the same folder. Plus, it will be easy to distinguish one project from another and the translated projects from the source project.

You can create your own conventions or use existing standard conventions. Per my client's request, the translations provider appended a standard ISO two-letter language code, followed by an underscore and the two-letter region code to the end of each translated project name, target name, and output folder name.

You can find the language codes in the ISO 639-1 column at http://www.loc.gov/standards/iso639-2/php/code_list.php External link. For region codes, go to http://www.iso.org/iso/country_codes/iso_3166_code_lists/
External link.

5 - Document Conventions and Processes in a Style Guide    

It is important to create a style guide for your project, but especially important if you hire a translations provider. A style guide enables you to communicate information about your project to the provider and minimizes the possibilities for errors, mis-communication, and unintended results. Your translations provider will be grateful if you create one!

Review the style guide with your provider in advance.

Give the translations provider your style guide to review before passing your project to them for translation. They will probably identify some things that need to be added. This will help ensure its completeness, and again, minimize the problems later on.

What to include in your style guide

Consider including the following content in your style guide:

English linguistic conventions

Include conventions for word usage, terminology, and capitalization.

Stylistic conventions

Identify which CSS styles to use in what circumstances.

List of "non-translatables"

List "non-translatables"-words and phrases that you don't want the translators to translate. For example, you wouldn't want to translate:

  • company names (Microsoft)
  • product names (MadCap Flare)
  • acronyms (XML)
  • path names that will be in the source language, for example: C:\program files\madcap software
  • program code
  • program parameters (such as CLIENT_NAME).
Target settings ("Single-source layouts" in RoboHelp)

Create a chart on which to record your targets settings. For each target include the following as applicable:

  • target name
  • master TOC
  • master page layout
  • master page
  • condition tags excluded from that target
  • output file name
  • alias file name (if you're creating context-sensitive help)
  • PDF settings
PDF properties not set in Flare

Describe your requirements for any PDF options not set in Flare. For example, you might want to add tags to your PDF documents so they can be reflowed and used with assistive software for accessibility purposes.

File and folder name conventions

Document the file and folder name conventions you are using. If you use standard ISO conventions, include a URL to the website where the translations provider can find the conventions.

Information about transferring project files and translated projects

Note how you will transfer files to and from the translations provider. Will you be using the provider's FTP site, your FTP site, or another mechanism to transfer project files and translated content?

Do not put credentials (and especially not passwords) in this document. Simply indicate the method for transferring files and the URL, if applicable.

Condition tags used

List each condition tag you use in your project and describe how you use it. Although this information is in your project, it's handy for translators to see it in the same place as your project documentation.

6 - Simplify Conditioned Text    

Don't apply more than one condition tag to a single sentence. If you need to vary the text within a sentence, create two sentences and tag each sentence for the output it goes with.


Suppose you are creating output for two versions of a software application, such as a Professional version and a Home version. You would create two condition tags as shown in Figure 1.

Figure 1: Condition tags for two versions of a software application

Let's say that you write one sentence that contains text variations for each of your two versions. There are two ways to apply these condition tags to your text.

Method 1: Apply multiple condition tags within the same sentence.

Figure 2: Two condition tags applied to text within one sentence

If you apply multiple condition tags within one sentence as shown in Figure 2, either the person translating the content or the person who prepares the content for the translator must piece together two different versions of the same sentence. This makes that person's job harder and more error prone. Instead, use the second method for tagging your content with a condition tag.

Method 2: Apply one condition tag to one sentence and another condition tag to a variation of the same sentence.

Figure 3: Two similar sentences, each tagged with a different condition tag

As you can see in Figure 3, the second method makes the sentences much easier to follow.

7 - Don't Embed Text in Images    

Create callouts and drawing elements with an application that supports layers (like MadCap Capture) so the text callouts can easily be translated. Create one layer for the screen shot and another for callouts or text labels. If callouts are embedded in the image, the image will have to be recreated in order for the callout text to be translated.

8 - Consider Whether to Translate Sample Data Used in Screen Shots    

Decide if you want sample data used for screen shots to be translated before recapturing screens in a localized user interface. Although this comes with a cost, it will make screen shots more meaningful for your international audience.

9 - Remove Extraneous Project Files (Targets, Topics, TOCs, Etc.)    

When I'm developing content in a Flare project, I often create extra topics, targets, page layouts, and TOCs. Projects can quickly get a bit messy. For example, I sometimes create temporary TOCs and targets for testing purposes, to try out variations of page layouts, or to build review drafts of topics.

In the past, I also created topics to document project design decisions, to hold notes about future enhancements, and to store information about release numbers and dates. I marked these topics with a condition tag that designated them as "Author Notes," and then I excluded that condition tag from all project targets to be sure these topics weren't included in my project output. I even included in-topic comments, much like a programmer includes comments in program code.

Additionally, my projects sometimes contain topics that are partially written. When writing about software, often a feature will be pulled at the last minute because it's not quite ready for release. You might have a topic nearly ready to go, except for some last-minute details. If the project weren't being translated, I would simply code the topic with a condition tag to exclude it from all output and it would be ready for me to finish for some future release. Because of my experience with translations, however, I now handle this differently. Now I pull these extraneous topics right out of the project before giving it to translators.

Dealing with all of these extra topics, project files, and coded comments is extra work for translators (which "translates" to extra cost) and increases the chances for errors. To avoid that issue, I stopped writing in-topic comments and I remove extra topics to a temporary folder outside the project hierarchy. By doing so, I minimize the chance that the extraneous content might get translated and included in the output.

There's no need for a translator to translate that content and build that output. Better to get rid of it before handing over the project.

10 - Identify Topic Content that Must Match the User Interface    

If you're writing about software, identify terms in your project that must match terms used in the software user interface. The translators will want to make sure that the translated term used in your project matches the translated term used in a software dialog or window. User interface terms include elements such as field names, window and dialog names, menu option text, tooltips, and error message text.

Here are two different ways in which you can identify user interface terms in your project:

  1. Create a span tag and apply that tag to user interface terms in your project's topics. The style you create should not apply any formatting to the text, as shown in this sample style rule:

    span.UITerm { }

    The advantage of this method is that once the source is coded, it's coded for all maintenance releases. You won't have to do a thing when future releases are translated except code any new terms with the span tag. The disadvantage is that it takes longer to apply span tags to every piece of text that matches the user interface; plus, it adds many more tags to your topics making them larger and harder to wade through when you view topic code.
  2. Build a Word or FrameMaker document that contains all of your project's final topics. Apply a style to text in the Word or FrameMaker document to identify text that should match the user interface. (I use a yellow background to highlight the text as though I were using a yellow highlighting marker on paper.) The advantage of this method is that it's fast to color-code the text. The disadvantage is that it's only good for one release because the color is applied to an output, not to your source.

So here's a bonus best practice because I just couldn't keep the list down to ten!

11 - Structure Content to Match the TOC Hierarchy    

Create a directory structure in the Content Explorer that matches the hierarchy of your TOC. Keeping the project folder structure the same as the Table of Contents again makes the project easier to follow for translators.

Lorraine Kupka has 18 years experience as an independent technical communicator writing documentation for end users and software developers. She authored the book Five Steps to MadCap Flare External link, and is a MadCap Advanced Developer for V6. Prior to her writing career, Lorraine designed and developed software, managed an Information Systems department and taught end-user training classes. She can be reached at lorraine@northcoastwriters.com.


Copyright © 2010 WritersUA. All Rights Reserved.
shannonm *at* writersua *dot* com
Published on August 27, 2010


The Conference for Software User Assistance

UI Text Design

WritersUA offers cutting-edge training and information to Technical Writers, Information Analysts and Architects, Documentation Designers, Help Authors, Publication Managers, Documentation Leads, Senior Writers and Documentation Contractors, and User Education Specialists. The focus is on software user assistance, which encompasses writing, editing, planning, coding, indexing, testing, programming, localization, and standards development.

WritersUA Home Page First Time Here Contact Us Join Our Mailing List OASIS Member RSS Resource Directory Tools Contractors Training Articles Blogs Web Resources