Variables and snippets are frequently used in MadCap Flare projects, and frequently they have an impact on the translation process. If authors don’t think about the translation when using them, the translators might run into considerable problems. So it’s often a good idea to flatten variables and snippets. MEINRAD explains what that means and how it affects the translation.
Project managers at translation agencies aren’t often asked to flatten things, even though flattening variables and sub-segment snippets can be hugely important when it comes to translating MadCap Flare projects. If your agency knows its way around Flare, they’ll probably ask you whether certain variables or sub-segment snippets can be flattened – or they may simply tell you that it has to be done. Flattening a variable/snippet means converting it to plain text so that it’s easier to translate. Whether that’s necessary for the translation depends on the content of the variable and how it’s used.
What are variables and what are the benefits of using them?
Variables are short sections of text without any formatting – good examples of variables are product names and numbers, version numbers and dates. The advantage is that if (for example) you’re updating a 1000-page manual where the product number comes up 500 times, you only have to change it once rather than 500 times. The CAT tools used by your translation agency work the same way: the variable is only translated once, and the translation is then inserted at the correct places in the target. This usually works smoothly with sections of texts that don’t change, and when updating and translating texts you save money because the content of the variable is the only thing that has changed.
When can variables cause problems, and what can you do to prevent them?
But variables are often created in ways which cause problems when translated into other languages. This can happen if words which need to be translated in the plain text, such as “online help guide”, “user manual” etc., are contained in the variable. There shouldn’t be any difficulties as long as the word is used in its basic form in a sentence, or on its own in a footnote – but it’s a different story if adjectival endings or verb conjugation mean that the word has to change! If so, using the basic form of the word in the variable would simply create more issues.
Another example is definite articles: although “the” in English is used for whatever word follows, in other languages these articles vary. So a simple “Refer to the <Variable>” won’t work as well in other languages, such as German, where you have to distinguish between “Siehe die Online-Hilfe” and “Siehe das Benutzerhandbuch”.
In order to translate variables like these correctly, they need to be flattened. The downside of that is the translated project no longer contains these variables, as they have been converted to plain text. That’s a drawback if you want to continue working with the translated Flare project, so you’ll have to weigh up whether a few small translation errors might be a price worth paying.
So in some situations, flattening variables isn’t a good idea. However, if you only need to print or publish the project, flattening problematic variables is something we would recommend. In any case, a translation agency with Flare expertise will know which variables should be flattened and will draw your attention to the issue.
Flattening sub-segment snippets
Sub-segment snippets are the other sections of texts which can benefit from being flattened before translation. These are snippets which don’t have a free-standing snippet tag and instead are part of another element, such as a paragraph. While free-standing snippets are usually a self-contained section of text, sub-segment snippets are highly likely to form part of sentences – and that can cause problems when the text is translated. Ideally, in order to minimize errors in the translation, you should avoid snippets containing parts of sentences and create self-contained snippets instead. If that’s not possible, flattening the snippets is the best option. This will remove the snippet and replace it with its “value”, i.e. it will convert it to plain text so that the translator can produce the correct translation without any problems.
Example:
Top tips for making variables und snippets suitable for translation
To avoid incorrect translations, we recommend taking a few things into account when producing the documentation in MadCap Flare:
- Only use variables for content such as units, version numbers, product names, brand names or names in general, and not for words like “device”, “operating instructions” etc. which will need to feature in the plain text.
- Don’t use parts of sentences in snippets.
- Try to create self-contained snippets and variables.
- If possible, try to think about how the sentence might be written in other languages when producing the documentation.
- When using numbers in variables, always add the unit to the variable. In some languages, the case changes depending on the number.
- If you’re using complex variables and snippets which absolutely have to be flattened, don’t use snippet variables as they can cause problems when flattening.
Not sure how to use MadCap Flare to produce texts suitable for translation? We can help!
Main image: © MEINRAD
