I recently took a summer vacation to Disney World in Orlando, Florida, and a specific scene in the Spaceship Earth ride in Epcot really caught my attention. The ride is centered on a voyage through time and space to explore how humans have communicated throughout the ages. It covers everything from ancient cave drawings to today’s internet age. The scene that really stuck with me involved monks painstakingly copying manuscripts with quills in intricate penmanship. It took days or even weeks to create a single copy of a book. The ride quickly progresses to the modern age with the creation of the printing press and then the advent of the personal computer.

I am sure those aforementioned monks would have loved to have had any type of shortcut to get through the creation of their books, which were undoubtedly tedious despite the original craftsmanship put into them. Fortunately, most popular authoring environments offer some shortcuts for technical writers creating user documentation — possibly the digital equivalent of copying manuscripts. This help comes in the form of conditional text, variables and cross-references.

I believe the original intent of these tools was to promote consistency through multiple documents and to allow the author to change small bits of text once in order to update many instances of the same text. Sounds simple enough. The problem occurs when the text needs to be translated into multiple languages. Other languages have different grammatical and capitalization rules and generally give technical writers migraines.

If technical writers and translation project managers keep a few suggestions in

mind, however, I think both parties can peacefully coexist and still use all three forms of generated text successfully. My goal is to illustrate how a writer sees each of the three types of text and how a linguist sees the same text. It is important to keep in mind that most translation environments separate this type of text into a distinct file or distinct part of the file (Figure 1). Linguists typically do not get to see the completely-built sentence in context from within their translation environment.

The easiest way to plow through this discussion is to tackle each of the three text types individually.

 

Variables

Variables are typically numbers, product names, company names, dates, version numbers or anything that might change from release to release. The obvious advantage is that something as simple as a revision letter or software version can be changed once and quickly applied across an entire manual or help system. See Figure 2 for an example of a variable used for a company name. The translator sees the term XYZ Corporation as a standalone segment as in Figure 3, and the actual sentence appears as in Figure 4.

Most customers use variables in a way that is easy enough to understand. Just as long as linguists can properly understand what text will be inserted into each sentence, they can typically make any appropriate adjustments in the copy to properly handle the inserted text. As you can see, clearly-named variables are extremely helpful.

Cross-references

Cross-references are intended to accurately cite other sections of a document or help system. These references are meant to assist users by pointing them to different sections that might be applicable to the information they need. Obviously, link-enabled PDFs and HTML-based help systems make this type of text useful, since users are just a click away from the information they need. 

This is where things start to get a little tricky for the linguist. Cross-references are typically used inside of sentences as in Figure 5. In the translation environment, the sentence appears as in Figure 6. It is important to note how the linguist has to change the order of the sentence and move the cross-references to the end of the sentence.

The actual heading looks something like Figure 7 in the translation environment. The actual cross-reference structure is seen in Figure 8. As you can see, there is nothing to translate here other than confirming that you want the dash to appear between the page number and the chapter number. The linguist could choose to invert the codes or add something if required, but in this case we don’t need to do anything.

In thinking of this type of text you can see a pattern emerging. We started with the smallest building block, variables, and moved to cross-references, which can be longer phrases or even sentences that are sometimes made of multiple variables. Now, we move on to what I would consider the largest of the three types of text, even though some people conditionalize tiny chunks of text, which I don’t agree with.

 

Conditional text

Conditional text is typically used when an author needs to cover multiple requirements for a given block of content. An example would be a series of products that start with a basic model with few features and moves up to a higher end product with many features. As you can imagine, much of the documentation would be identical in all models. Typical product warnings, caution statements and some of the user instructions would be the same across all models.

Conditional text, if handled properly, would be a handy thing for the author to use. Let’s start with the incorrect way of handling conditional text by looking at an example (Figure 9).

This seems easy enough — the Model 400 has the ability to store 50 sets of pre-configured settings, and the Model 450 can store 100 sets. However, in a translation environment that same sentence is a little murky (Figure 10). It is really difficult to tell which condition goes with which number. The risk here is an incorrect translation. Conditionalizing complete sentences or thoughts is a far better way to handle this, as shown in Figure 11. Now the linguist will have an easy understanding of the content as well. You can see in Figure 12 that the segments are now two distinct sentences.

Some might argue that this will inflate the word count and the cost of the final translation. I don’t believe this would be a significant cost. Once the first sentence is translated and in the translation memory, subsequent versions of the sentence will come up as fuzzy matches, resulting in discounts. Also, this simple change in how you build your conditional text will prevent errors in the final translation.

The examples I provided were somewhat simplistic in nature and didn’t even come close to all of the uses of variables, cross-references and conditional text in your documentation. But this article should give you the ability to speak to your language service provider (LSP) about how to provide your content in a way that works with their translation environment and their linguists.

I would suggest these key points to remember when working with this type of text and your translation projects:

Keep your content as flexible as possible. Understand that your linguist may need to move the tags around in the structure of each segment to make the generated text work properly in a given language. Some languages may even need to add declensions to the end of some variables but not others. The linguist must have the ability to understand how the content will come out of your system. Post-formatting checks of the documents are essential, especially in the beginning of your relationship.

Remember the one-to-many re-lationship. I can’t tell you how many times I have heard “Well, there should be some sort of workaround to make the generated text work properly in translation.” Yes, if a problem presents itself in step 1, the LSP can open the target files and make a manual adjustment. But let’s say a specific issue occurs ten times per manual, and your project is in 28 languages. Do you really want to have your LSP make 280 manual adjustments? What does that do to your timeline and cost? It is far better to make things work properly in step 1.

Don’t include your development notebook. We have seen many clients include content in conditional text that is not meant for translation. In one instance we found conditional content that was in development for the next product release and not intended for translation at all. I would make it a practice to prepare your files for translation by excluding that type of content entirely so that it doesn’t get included in the scope of your project.

Communicate regularly about how projects are going. It is important to have an open line of communication between the LSP and the client. Rather than struggle through issues it is far better to discuss what types of changes can make the process smoother for either party.