MadCap Flare Translation

MadCap Flare™ is a powerful authoring tool with a wide range of features for creating sophisticated outputs.

The fact that Flare enables the creation of this range of documentation sometimes creates a challenge when translating its content.

Translating Flare is considered quite intimidating for technical translation service providers. MadCap prides itself for its single-source feature, which is dependent on powerful features, such as variables, snippets, conditional text, links, CSS files and more and more, and all this can be very confusing for the individual translator or translation agency.

Apart from this, any Flare project can be different. Therefore, generating a fully compatible functional translation, taking into account all of the Flare project’s unique aspects, requires high proficiency with Flare compared to other authoring tools.

We at LingoTip offer Flare translation service as a one-stop shop. Once we receive the Flare project from our customer, we study the project, prepare it for translation, and provide back a complete Flare project as well as the target output format in the target language after final DTP.

 Here are some guidelines that may assist technical writers to author a Flare project that is designed for translation.

 Technical correctness of the Flare project

It is important to make sure that the original Flare project is correctly constructed—that there are no missing or broken links, broken references, missing topics or tag errors.

If this step is skipped, then these issues will be carried over to the translated languages and we’ll have to deal with these issues multiple times. For this purpose, we always analyze the Flare project and create a 100% ready version for translation.

It also makes sense that we create a target for translation to ensure that no file/folder is missing due to broken links or references as a result of the client’s network structure. So, it’s critical to ensure that no errors occur when building the output prior to translation.

Structure of the Flare project

A Flare project can be simple or very complex. The structure is basically similar for all projects, but the location of files may vary based on the author. In addition, the location of the images or snippets may vary from project to project. Layout files may contain translatable text, so it is important to double-check and create a list of files that contain translatable text.

It is important to choose a translation company with the know-how and tools for extracting the relevant files for translation. This could be challenging, especially in case of complex projects that require multiple targets containing variables, conditional text, etc.

Snippets, Variables and Conditions

Snippets, variables and conditions are sometimes heavily used and often impact the translation process.

Snippets are important files, containing repeated text, used for single-sourcing and act as a mini-topic. When designing a Flare project, it is important not to use snippets in partial sentences. When a snippet is a partial sentence, it causes two problems. The first is that the translator does not see the snippet as part of the complete context (a snippet file is just another file from a long list of Flare project files), and the second is that the structures of different languages differ and may require changing the order of the snippets. Therefore, the final translation may sound strange if snippets are used in partial sentences.

Variables are short pieces of content, such as a product name, phone number, version number, dates, and so on. The variable can be edited in one place and can be used many times throughout the project.

Sometimes the authors get creative, creating variables that may cause issues in the translation. In those cases, the translation requires creativity as well when the structure of the translated language is different from the source. Here, again, the translator sees a combination of tags and text and needs to guess the range of possible targets and translate accordingly.

Therefore, words that are sometimes used in variables by Flare authors, such as “machine”, “device”, “user manual”, should NOT be used as variables if the project is going to be translated.

Before the translation, when studying all the variables, we may decide to “flatten” certain variables. Flattening a variable is a process by which the variable tag is replaced by its value. Flattening variables is not always the best method and the author of the Flare project should be consulted prior to deciding which variables to flatten and which to leave as a variable.

Regarding conditional text, the author should avoid having multiple conditions in a single sentence (segment), otherwise it’ll be almost impossible to translate correctly due to different language structures.

From a single-source perspective, it’s impressive how authors play with variables and it can be great as long as the project does not require translation. When translation is required it is important to think about the consequences on other languages – to correctly design for localization. The best recommendation for authors is to keep it simple.

Here are some guidelines:

1. Only use variables for numbers, non-textual text, product names, brand names or names in general. NEVER use variables for words such as “device”, “machine” or “instruction manual”.
2. Don’t put multiple conditions in a single sentence.
3. Don’t use snippets in partial sentences.
4. If you happen to speak a second language, try to foresee how the sentence will be understood in a second language.

Special Formatting

1. Consider that the same content in different languages may take up a different amount of space—up to 30%-50% more. For example, there is a significant difference between text in Japanese and text in German. This means that most likely formatting changes may be required after the translation to adjust for page breaks, tables, columns and so on.
2. Dealing with translating from LTR into RTL languages could potentially require further formatting work as well. Furthermore, sometimes there are directional icons, such as:   that work well for LTR language but not for RTL languages, such as Arabic and Hebrew, so the author should consider avoiding directionally related icons.
3. Always use CSS styles instead of local formatting or inline styles.

Summary for Authors

1. Make sure that the Flare project is complete and contains no errors.
2. Use snippets, variables and conditions wisely.
3. If you speak a second language, you should take advantage of this knowledge to debug sentences with conditions/variables to try and figure out if it is translation friendly.
4. Try to keep the sentences as simple as possible.
5. Try to keep the layout as simple as possible and reserve space for text expansion.
6. Refrain from using text boxes. They may look good, but may cause problems in some languages.
7. Try to avoid using images with text.
8. Discuss the structure of the project with the translator (variables, conditions, snippets), layout files that may contain translatable text, etc…

If you need further information about the Flare translation process or require the translation of a Flare project, please contact us and we’ll gladly offer our services and expertise.