Because sentence structure can change a lot depending on the target language, be aware of the following general guidelines when using these powerful features.

Snippets

• Do not use snippets in partial sentences. This can cause problems in translation because translators see each part of the sentence separately. Each snippet is its own file in a long list of other files, making it difficult for translators to know its context.
• Snippets are best for single elements, rather than using as a variable that fits into a sentence, unless the variable does not change (e.g., product name, brand name, or proper noun).

Variables

• Keep variables simple. Translators see variables embedded in sentences, and not the context of the variable.

  Tip An advantage to using MadCap Lingo for managing files for translation is that it allows you to select and flatten variables to convert them to text. By doing this, translators retrieve and view the real text only, rather than the tag.

• Avoid using common nouns, or generic terms as variables (e.g., device, machine, instruction guide, manual).
• Only use variables for proper nouns, dates, version numbers, addresses, or non-textual information for targets.

• Avoid using inline variables. It is better to put a condition on a whole sentence. Using inline variables can present improper conjugation and noun-verb agreement problems for languages that are gender-specific.

  Example  

  If translating from English to Spanish, consider the following sentence: The <variable> is tall.

  The variable is either girl, or boy. In Spanish, the article and the adjective change, based on the gender of the noun.

  The translation with girl as the variable is la niña es alta, and with boy it is el niño es alto.

  The cleaner solution is to write two sentences, and apply a condition to each one.

Conditions

• Avoid conditions that change sentence structure; meaning do not put more than one condition in a single sentence. Instead, write two simple sentences and condition each. For some languages, the grammar and word form can change depending on singular vs plural elements, the gender of the noun, or verb tense, etc.

  Example In this example, a condition is applied with an “s” to add a plural form to a sentence. In the Flare image below, notice the use of singular and plural in one sentence with condition tags.

  

  Keep in mind that other languages do not allow the translator to simply add an “s” to make a word plural. In the computer-assisted translation (CAT) tool, the translator is faced with figuring out a rather complicated text string. The following image is what they see in the CAT tool.

  

  The better way to approach this sentence is to create two sentences and apply one condition tag to the entire sentence.

  Some might wonder if creating two sentences instead of one will increase translation costs. But if you write two cleaner sentences from the start, that enables the translator to interpret what is going on better in order to produce accurately translated material. This simplified method reduces the likelihood of rework, thereby reducing costs in the long run.

• Avoid using condition tags for internal only notes. If you do, label them as such at the topic level (not within topics) so they get omitted from word count. It is better to create notes with Flare annotations. See Inserting Annotations.

Tag Placement

As you can imagine, a lot of tags applied to content intended for translation can reduce content clarity and increase its complexity. Translators have to work around tags, but authors can help the efficiency of translations by optimizing tag placement.

• Reduce the use of, or avoid using inline tags (e.g., no closed tags in the middle of a word).
• Turn hyperlinks into cross-references when possible. Cross-references are easier to handle, and require less integration.
• Avoid inline styles. Create style classes in the stylesheet instead.