You've authored your Flare project, and everything works perfectly – but will it still work well in translation? Have you used Flare’s features in the best way, or will your project have problems in other languages? With our experience in both Flare and translation, we’ve seen a lot of the good and the bad. To help you prepare for your translation effort, we’ve come up with six common issues spotted in Flare projects submitted for translation, with recommendations on how to correct or avoid each one.
#1: HYPERLINKS TO TOPICS
When referencing other Flare topics using hyperlinks, the link text is set in that current topic. It can be a demonstrative phrase (such as the “here” in “click here to see…”), or it can be simply the linked topic’s header. If the link text is just the topic header, then in translation it is ideal for links like these to be cross-references instead of hyperlinks. With cross-references, there is no risk of inconsistent translation between the link text and the topic header itself and no need to manually update each instance to ensure consistency, since cross-reference text is automatically generated and doesn’t require translation.
Another option that would work in some instances, where lists of linked topics appear, would be to use a mini-TOC, a relationship table, or even a list-of. All three of those features can automatically generate lists of topics that are specified in different ways: TOC organization, user-defined relationships, or tag elements (optionally with specific style classes). All of these features reduce the need for extraneous translation effort and make maintaining consistency very easy.
#2: HARD-CODED IMAGE DIMENSIONS
Many authors are tempted to resize their images manually in Flare, which leaves images with their height and width hard-coded into the topics. Hard-coded height and width can cause issues in translation for any images that will be localized (either screenshots, or images with callouts), because the localized image size might be different. After being placed into the project, the localized image will appear distorted as it is subjected to the original image dimensions. In those cases, the dimensions would need to be reset manually for each such image – for projects with over 20 localized images, that quickly becomes a large task. However, thankfully, these image size adjustments can usually be made in better ways.
If you need to resize your images, then we recommend two approaches: (1) Set a max-width on images in the stylesheet, to prevent them all being too large for the PDF page (using the Print medium) or even the Web page (using the Non-Print medium). This will apply the size restrictions to all images appearing in these outputs, unless you setup an image class to be applied to only specific images. (2) For an individual image, set the most important dimension to a specific size, and then set the other dimension to “auto” to enable that dimension to adjust to the proper size to maintain the image proportion. This restricts the image size effectively, while allowing the proportions to change if the image changes. (Also maybe add something here about using Capture for image callouts/text expansion issues).
#3: FLAT IMAGES WITH CALLOUTS
Another potential issue relating to images is using “flat” images with callouts in your Flare project. By “flat”, we mean that any text in callouts, diagrams, etc. is completely embedded into the image, and it is not “live” (or editable) in a software program. Photoshop itself has live or editable text, but the images that it produces are considered flat. Now, there’s nothing wrong with using Photoshop or other image editing tools (as long as the source files with editable text are provided for translation), and some images warrant the extra toolset and editing power. However, you don’t get to make use of some great benefits in translation that MadCap Capture provides.
MadCap Capture has editable text in layered objects, in a similar way as Photoshop and several other tools. Where they differ is in (1) the ease of translation, (2) the coordination with your Flare project, and (3) the new automatic expansion options in Flare. Capture images store text in an XML-based .props file, which allows for immediate translation of the text, without any manual extraction of the text or copying it back into the software environment after translation. In addition, Capture allows you as an author to make use of your Flare project’s conditions and variables, enabling you to single-source your images if needed. And finally, Flare 10’s new auto-size of Capture callouts will expand the text boxes to fit the translated text, which is usually larger than the original English text. You can retain tighter control over that functionality by using anchors on your callouts, which will essentially show Flare which dimensions can be expanded, and which can’t.
#4: EXTRANEOUS SPAN AND BOLD TAGS
When migrating legacy content from other sources, you may notice several instances of extra span tags or bold tags that are not necessary. For instance, a few tags that apply no style or class, and some phrases where the same span or bold tag is applied multiple times to make the entire phrase styled the same way. It is usually a good idea to prep files by removing these extraneous tags before translation, because the translation process is easier when inline tags are kept to only what’s necessary. We frequently do this ourselves as part of a project setup step.
Along similar lines, it is a best practice to avoid inline style formatting (i.e., using instead of applying a class such as or using the built-in tag ). While this may not produce extraneous tags, it does create extraneous formatting. In many languages, font styles and font families need to be changed to something more appropriate for their script. If these changes have to be made in each topic and snippet in the project, that can take some extra time. However, if all formatting is applied through classes or proper tags (such as , or ), then the formatting can be changed in the stylesheet, which will immediately apply the changes throughout the project.
#5: COMMON NOUNS AS VARIABLES
Common nouns should generally be avoided as variables. For example: “device”, “Device”, “application”, “User Manual” (when used as an object in a sentence, not as the document title). While these variables work in English, they often don’t work in other languages. In translation, a word like “device” might need to have different spelling depending on the context where it appears (depending on the part of speech, the other words around it, etc.). If the common-noun variable is inserted into 10 different locations, there might be 3-4 different spellings required. And if the variable actually has different values in different targets (for instance, using “device” in one and “product” in another), that can upset the translation of the topics where the variables appear even more. There are ways to work around these issues, but they do take more time and energy, and make the translation process less efficient.
#6: XREF FORMAT (INLINE, WITH PERIOD)
The MadCap:xref auto-text format is very important for translation. We generally recommend that cross-references are designed to either standalone or contain just the cross-reference text with no punctuation (such as “{paratext}” or possibly “see {paratext}” if inserted inside of complete sentences). If you have a format that is not a complete, standalone sentence, and yet contains punctuation (such as “see {paratext} {pageref}.”), we would recommend removing the period from the auto-text format and putting it after the xref tag in the topic’s content instead. This is because with some languages, especially Asian ones like Japanese, the cross-reference actually goes at the beginning of the sentence and not at the end. The “see” can usually be left in the auto-text, since the usage of the cross-references would still look correct grammatically and since Asian languages don’t have capitalization.
Occasionally these extra words in inline cross-reference formats can cause issues, either in certain languages or in certain contexts, but generally speaking they are fine as long as the overall sentence, including the cross-reference, is grammatically correct.
ONE FINAL RECOMMENDATION
We are always happy to check your Flare project for localization issues, or to give you advice on handling your own unique situations or requirements.
If you have any questions or would like to request a free quote from MadTranslations, feel free to contact us at sales@madtranslations.com.
