For reasons I won’t go into, I’m not a fan of MadCap Lingo. So when I needed to get my MadCap Flare project translated into 4 different languages, I came up with an alternative solution using an open source tool called Rainbow. I am sharing my approach here for the benefit of others.
DISCLAIMER: The below has worked for me – so far. My translations are still ongoing. It’s entirely possible that 1) my methods don’t work for your project and 2) I run into problems with my own project later on. Nevertheless, I am hoping this will get you at least part of the way there. You’re always welcome to ask me questions if you think I can help.
Rainbow, which is bundled with the Okapi Framework apps
NOTE: Some people have reported problems running the 64-bit version of Rainbow. If that’s the case for you, install the 32-bit version. It works exactly the same.
In addition to the above, it helps if you have:
You can approach the translation of your Flare project in two ways. You can either translate your original project files (pre-build), or you can translate the actual output (post-build). My process uses the first approach, but here are some pros and cons for both options:
Translating the project:
Translating the output:
Although there are several reasons why I chose the first approach, that last one clinched it for me. If image annotations are not a factor for you, perhaps it might be easier to just zip the output and send it off to your translator or LSP.
Here’s what you’ll roughly be doing if you follow my instructions:
This is just to provide an overview. It is not a table of contents.
Open your project in Flare and select Project > Export Project to create a copy. Tips:
Select Export From > Using Conditions to exclude drafts and other files you don’t want translated.
NOTE: You could use a special condition tag to explicitly mark files for translation, but make sure you export all the files you need to be able to build the project at the end.
I recommend appending the filename of the exported project with the source and target language codes. E.g. if you’re translating from (US) English to French, save as
Open the exported project and select Project > Project Properties.
Under Language, select the target language. This should take care of any translatable labels in your project skins (e.g. search box place holder, topic toolbar buttons), provided that 1) Flare has default translations for the chosen language and 2) you have configured your skins to use the default project language.
Rainbow is sort of a Swiss army knife for translators and translation project managers. It offers file conversion, terminology extraction, quality checks, pre-translation, and about a million other things I haven’t even begun to explore myself. Unfortunately, it’s also got a steep learning curve. There’s a wiki which is fairly comprehensive, but it often lacks detail in important areas, and some parts seem out of date. Thankfully, you’ve got this blog to help you!
Fire up Rainbow and do these things:
On the same tab, set the encoding for source and target to Unicode (UTF-8).
NOTE: This was the correct encoding for my project files – I assume it’s the same for all Flare projects. You can check by opening one of your topics in a program like Notepad++.
On the Other Settings tab, de-select Use an extension. This is important because you want the final, translated files to retain their original names. Under the default settings,
Save your configuration (File > Save).
Files I have not tried to translate, as my project doesn’t use them:
Files that need special treatment (will cover this in a future update – ignore them for now):
Rainbow includes a large set of filter configurations, which you can see by selecting Tools > Filter Configurations. Rainbow uses these filters to determine which parts of a given file are translatable, i.e. which parts it should extract and put in a translation package.
A Flare project consists of HTML and XML files. Rainbow has default filters for these file types, but they will only work for a few of your files. You’ll have to create custom filters for the rest.
.flglo) and variable sets (
The default okf_xml filter will work for glossaries and variable sets. To apply this filter:
Under Filter configuration, select XML Filter.
In the Filter Configuration column, it should say okf_xml.
.htm), snippets (
.flsnp) and master pages (
Click Create to create a custom filter configuration based on okf_html.
Enter the name
flare-topic and click OK. The full name will appear as
The filter’s parameters now appear. This particular filter uses the YAML format.
preserve_whitespace: false to
true. This ensures that the whitespace around e.g. cross-references is retained during conversion.
Scroll down a little until you see
elements: and insert the following lines immediately after it:
madcap:variable: ruleTypes: [INLINE] SelementType: variable
This ensures proper handling of in-line variables. (They are treated as line breaks otherwise.)
Click OK to close the editor, then OK to return to the file list.
Now is probably a good time to save your Rainbow configuration file, so select File > Save.
.fltoc files and create a new filter called
Unsurprisingly, the parameters of this filter are written in XML.
Replace the default parameters with the following:
<?xml version="1.0" encoding="UTF-8" standalone="no"?> <its:rules xmlns:its="http://www.w3.org/2005/11/its" xmlns:itsx="http://www.w3.org/2008/12/its-extensions" xmlns:okp="okapi-framework:xmlfilter-options" xmlns:xlink="http://www.w3.org/1999/xlink" version="1.0"> <its:translateRule selector="//@Title" translate="yes"/> <!-- See ITS specification at: http://www.w3.org/TR/its/ --> </its:rules>
This tells Rainbow that the values of all
Title attributes contain translatable text. (By default, attributes in XML files are considered non-translatable.)
.props files and create a new filter called
okf_xml@flare-props, containing this code:
<?xml version="1.0" encoding="UTF-8" standalone="no"?> <its:rules xmlns:its="http://www.w3.org/2005/11/its" xmlns:itsx="http://www.w3.org/2008/12/its-extensions" xmlns:okp="okapi-framework:xmlfilter-options" xmlns:xlink="http://www.w3.org/1999/xlink" version="1.0"> <its:translateRule selector="//fileProperties" translate="no"/> <its:translateRule selector="//Shape[@Type='Annotation']" translate="yes"/> <!-- See ITS specification at: http://www.w3.org/TR/its/ --> </its:rules>
This tells rainbow that all
<fileProperties> elements and their children should be ignored, except when one of those children is a
It’s a good idea to back up your custom filters for future translation projects. By default, they are stored in Rainbow’s installation directory, in a subfolder called
config. You can keep them there, or organize them by project/client/category/whatever.
A fundamental feature of Rainbow is that it lets you build conversion ‘pipelines’, which enable you to put in a bunch of files on one end (i.e. source texts, terminology files, translation memories) and produce a neat little translation package at the other, which you can then send off to a translator/LSP.
You can build your pipelines from scratch by choosing from dozens of configurable steps, but for the present purposes you can use one of Rainbow’s pre-defined pipelines.
Select Utilities > Translation Kit Creation. This fires up the pre-defined pipeline for creating translation packages.
In the list of steps on the left, select the bottom one (Rainbow Translation Kit Creation).
On the Package Format tab, select Generic XLIFF.
NOTE: Any CAT tool worth its salt (e.g. Trados, MemoQ, OmegaT) can handle XLIFF, so that’s the format I use. But you can theoretically use any of the other formats as well – you just won’t be able to use my instructions from hereon.
Click Options and make sure these options are selected (they might be by default, I’m not sure):
On the Output Location tab, choose an output folder and give the package a name. I recommend mentioning the source and target language in both.
Optionally, add any translation memories, terminology files and other supporting documents on the Support Material tab.
When you’re ready, click Execute.
Rainbow now goes through each file, extracts translatable text based on your filter configurations, splits that text into segments (i.e. sentences) and stores it all in XLIFF (
.xlf) files. There will be one XLIFF file for each source file.
Don’t worry if the log contains mildly alarming messages like
Trying to end a TextUnit that does not exist. As long as the error and warning counts at the bottom are both at 0, everything is fine.
If things went as they should, your output folder will contain these things:
original, which contains the original source files (for the translator’s reference).
work, which contains all the translatable
manifest.rkm, which contains information about where each individual translatable text came from. Rainbow uses this to determine where to insert the translations as it converts the translated files back to their original formats.
If you want, you can open your files in OmegaT to see how they look for the translator.
As I mentioned earlier, any serious CAT tool should be able to handle XLIFF files. By the same token, so should any serious translator. If your translator says they can’t work with XLIFF, find another translator.
You can email the files in a zip file, host them on Dropbox, or transfer them any other way you want. It doesn’t really matter, as long as:
workfolder is kept intact;
manifest.rkmfile is not tampered with.
In fact, I recommend not even sending the manifest file. The translator has no use for it.
If everything went as it should, the translator should send you back the same basic set of files, with the same folder structure, except all the
.xlf files have been modified. You can open them with a text editor and see that each source segment now has a matching translation. You’re now going to run these files through Rainbow again to convert them back to their original format.
In Rainbow, create a new configuration file (File > New).
NOTE: If you’re like me, you’d expect to load up your previous configuration and continue where you left off. But that’s not how Rainbow works – you really do need a fresh config.
manifest.rkm file into the file list.
Select Utilities > Translation Kit Post-Processing. This loads up another pre-defined pipeline that more or less does the reverse of the one you used previously.
Click Execute. You’ll see an overview of all the files that are going to be post-processed.
The converted, translated files will be in a folder called
done, on the same level als the
Copy the translated files into your target-language project folder. Build the project. Done!