Localization Guidelines for Technical Communicators

By Thomas Albert 14 December, 1999 talbert747@gmail.com

Table of Contents

Glossary
Guidelines

Objectives of These Guidelines
Guideline Format
General Principles
Consistency
Grammar: Word Level
Grammar: Sentence Level
Grammar: Modal Auxiliaries (will, would, may, might, can, could, should, shall, have to, ought to, must)

Engineering Considerations for the Localization

Text Considerations
Graphics Considerations
Cultural Sensitivity
For the Developer

References


Glossary

Translation
The act of converting verbal expressions from one human language to another.
(Translation does not modify the look and feel of the product for the target culture.)
 
Localization, also known as L10N
Localization is the process of modifying a product (software and its documentation) for an audience in a different country, culture, or region of the world. Localization is more than translation because it involves changes to the software product.
  • Translation
  • Text support - the kind of text characters (1- or 2-byte), and the migration of text in resources files
  • Graphic design - what the artist depicts and how, including accommodation for text expansion
  • Cultural adaptation - adjusting images, text, margins, lines, color, and so on, for the customs of the target locale. This is particularly important for marketing
  • Legal adaptation adjusting the product/documentation for the legal requirements of the target locale

Ideally, the software team plans for localization from the very beginning of the software development cycle, instead of as an afterthought at the end. A well organized localization effort

  • can enable product release for foreign markets that is simultaneous with the initial release in the home market
  • involves a process of iterative development analogous to that of the best practices in software development
  • allows the internationalization team to start early in the development cycle and maximize reuse of already localized "components"
Internationalization, also known as I18N
The act of (re)designing a document or software product for general markets beyond the boundaries of one nation. Does not include adaptation for a specific cultural/legal locale.
Globalization, also known as G11N
Synonymous with Internationalization.
 
Text Expansion
The effect of translation: typically a sentence requires 30% to 100% more horizontal space (especially for German), and can require 30% more vertical space (for Chinese).
 
Text expansion affects
  • the user interface
  • diagrams and screenshot frames with embedded labels (callouts)
  • page count  (unless the translator revises text to constrain page count, which takes time)

Guidelines

Objectives of These Guidelines

The key goal of localizability is that the writing be clear (avoid ambiguity) and simple (easy to read or speed read). When technical communicators optimize their writing style for localization, everyone wins:

 Guideline Format

Key idea
Original draft Revision Commentary

General Principles

  1.  
    Write (or revise) each sentence to be short and simple (16 words or less).
        Be willing to break a long sentence into two or three smaller sentences.
  2.  
    One idea per sentence; one sentence per idea; do not use semicolons (like I just did) because the translator has no clear way to interpret the relation you imply (contrast, similarity, illustration). Colons are simple and direct.
    One idea per sentence; one sentence per idea; do not use semicolons. Write only one idea in each sentence. Express each idea in only sentence. Do not use semicolons to link sentences.  
  3.  
    Use the paragraph as the module to develop a topic.
        Translator often combine (or break up) phrases and sentences. However, translators keep the paragraph-by-paragraph blocks of text.
  4.  
    Use the active voice, present tense, and clear referents.
    When the results were announced by the researchers, they were questioned by others Experts questioned the results that the researchers announced. "they" refers to results or researchers? "others" refers to results or researchers?

    5.

    Use the active voice, present tense, and clear referents.
    When the results were announced by the researchers, they were questioned by others Experts questioned the results that the researchers announced. "they" refers to results or researchers? "others" refers to results or researchers?

    6.

Use visual cues: paragraphs, bullets, numbered steps, charts, diagrams.
Avoid words that can have multiple meanings (for example, while, as, so and since), which can confuse the translator and often do not have a direct equivalent in the target language. Avoid words with multiple meanings, such as
  • "while" (during vs. in contrast to)
  • "as" (during vs because)
  • "so" (also vs. because vs. to a great extent)
  • "since" (after vs. because)
  1.  
    Do not use contractions.
    You can't back up and recover data at the same time, instead you'll get an error. You cannot back up and recover data at the same time. If you try to do so, the system displays an error message. The original has a comma splice. The revision also resolved the future tense into the present tense.
  2.  
    Use standard English instead of slang or insider humor.
    An error message, such as 'blah, blah, blah' appears." An error message displays, such as 'Unable to perform task'  
  3.  
    Avoid non-standard, idiomatic expressions.
    The out-of-the-box configuration The configuration that comes with the product

    OR

    The default configuration of the product

     
  4.  
    Do not use abbreviations unless you are certain the audience understands the meaning.
    10 Mb 10 megabytes (MB) Define an acronym the first time you use it.
  5.  
    Unpack noun strings.
    Do a manual page count. Count the pages by hand.

    OR

    Use a software feature to obtain the total number of pages in the manual.

    Is "manual" a noun or an adjective that modifies page count?
    Use the downloadable automatic program update utility. Download the utility that automatically updates the program. Instead of "use", which is vague, "download" is a precise verb.
  6.  
    Avoid the slash inside words: "and/or", "s/he" because the translator might think you are giving a file path.
  1.  
    Use English, not Latin
    e.g.

    i.e.

    via email

    for example,

    that is,

    using email

     

     

    Consistency

  2.  
    Use each term in a limited, consistent manner.
    When you install the Oracle server on your server When you install the Oracle database on your server machine. "server" as either a hardware or software but not both interchangeably
  1.  
    Do not alternate between terms.    
    Step 1:

    Step 2: exit the Installer.

    Step 3:

    Step 4: quit the Installer

      The translator will spend time trying to figure out why the verb changed from "exit" to "quit", and whether to duplicate the change in the target language.

    Pick one: exit, quit, shut down

        Pick one: display, show, or appear
        Pick one: verify, make sure, ensure
        Pick one (for cross-references): see, refer to, look up
  2.  
    Change "in order to" to "to"
    In order to start the application To start the application.  
  1.  
    Confine a word to a single part of speech (noun, verb, adjective)
    To clear the display so that it displays a clear screen To clear the display so that the monitor has a blank screen  
    Archive the critical files for your release in an archive.

    OR

    File the critical files for your release in an archive.

    Store the critical files for your release in an archive.  
    The button control controls what happens when the user clicks on the button. Code associated with the button control determines what happens when the user clicks on the button. Use control as a noun for the user interface.

    Do not use control as a verb.

  2.  
    Spell out acronyms at first use.
    The STC .

    The STC (Society for Technical Communication)

    The Society for Technical Communication (STC) Similarly, define a term the first time you use it.

     

    Grammar: Word Level

  3.  
    Do not omit the article ("the", "a", "an")
    Download utility that updates program Download the utility that updates the program. The article provides clarity, and in this case indicates that "download" is a verb instead of an adjective.

    Check your callouts for missing articles.

  4.  
    Use hyphens for compound nouns.
    Eight week long courses Eight week-long courses

    OR

    Eight-week-long-courses

    Unpack the hyphenated noun string "Eight-week-long-courses" into "courses that are eight weeks long"
         
  5.  
Use "once" to mean "one time" not "after".
Once you copy the data onto a floppy, delete the original file, select Duplicate onto CD once for each additional copy you want." After you copy the data onto a floppy, select Duplicate onto CD once for each additional copy you want." The revision
  • resolves the ambiguity of "once"
  • highlights the UI item for clarity
  1.  
Use "first" instead of "until"
Until all team members have been trained, it's not a good idea to begin the process. First train all team members, and then begin the process. The revision
  • has an active procedure
  • uses the active voice
  • is positive (avoids "not")
  • is shorter

 

Grammar: Sentence Level

  1.  
    Use a comma to introduce a restrictive clause (a "which" clause).
    A computer which has an electronic memory, retrieves data quickly. A computer, which has an electronic memory, retrieves data quickly.  
  2.  
    Use "that" without a comma to introduce a non-restrictive clause.
    A computer which has a large amount of RAM can manipulate large graphic files A computer that has a large amount of RAM can manipulate large graphic files.  
    There are courses eight weeks long. There are courses that are eight weeks long.

    OR

    For a period of eight weeks, courses will be available.

    Although "that" makes the sentence longer, it also makes the sentence clearer.
    It is critical you back up your database. It is critical that you back up your database "that" marks the start of an embedded clause.
  3.  
    Resolve dangling modifiers.
    When running in character mode, you must quit the browser after you finish reading the help text; the Installer is suspended until the browser is terminated. Running the browser suspends the Installer, which runs in character mode. If you want to read the Help text in the browser, make sure that close the browser before you attempt to continue using the Installer. Who or what is "running in character mode"? The installer or the user?

     

    Grammar: Modal Auxiliaries (will, would, may, might, can, could, should, shall, have to, ought to, must)

  4.  
    Resolve the ambiguity of "may" into "might" or "can".
    You may notice that if your floppy disk is full, it may not allow you to save more files onto it. You might notice that if your floppy disk is full, you cannot save more files onto it. 80% of the time, "may" means "might".

    20% of the time, "may" means "can".

  5.  
    Resolve the ambiguity of "may" or "might" into "if".
    You might notice that if your floppy disk is full, you cannot save more files onto it. If your floppy disk is full, you cannot save more files onto it. If you have time, instead of merely resolving "may" into "might" versus "can," eliminate modal auxiliaries.
  6.  
Resolve the ambiguity of "should", which can mean advice/obligation or expectation.
When you install this application, you should have 150 MB of free disk space. Before you install this application, verify that you have at least 150 MB of free disk space on your hard drive. Is having the space a prerequisite or a result? If it is a prerequisite, "should" is too soft, and "must" is better.
You should [advice/obligation] notice that the data should [expectation] already be copied onto the floppy. Verify that a copy of the data is already on the floppy. The original has a comma splice. The revision also resolved the future tense into the present tense.

 

Cultural Factors

  1.  
    Think globally in your geographical references.
    If your company has offices in Cupertino, Santa Clara, and Sunnyvale. If your company has offices in Tokyo, Paris, and New York.  
  2.  
    Think globally in your date references.
    Suppose it is New Year's Day, and Suppose it is the first day in January, and  
  3.  
    Think globally in your hour references.
    Suppose it is 7 p.m. Suppose it is seven o'clock in the evening  
  1.  
    Think globally in your date formats.
    Your table has a single column called "date" with fields such as "12/4/99" Your table has three separate columns for "year," "month," and "day". "99-12-04" for Sweden

    "4.12.99" for Germany

  2.  
    Think globally in your numeric formats.
        12,043.47 in USA

    12.043,47 (or a variant) in Europe

  3.  
    Use both the metric and imperial measures, and do not abbreviate foot as ' and inch as " [or use "" to mean ditto] or lbs or # for pounds (be aware that "pound" in the U.K. is also a unit of currency).
  4.  
Be aware that numbers and colors can have negative connotations:
  • 13, 4 (Asia), 666 (New Testament)
  • colors that make a local audience think of the flag of a certain nation

 


 

Engineering Considerations for the Localization

Text considerations

 

Graphics considerations

 

Cultural sensitivity

 

For the developer

Edit string resources, instead of the code. Source code should not contain strings because you cannot predict where the string replacement occurs in the target language.

Example:


References

  1. "Writing for International Audiences", Silicon Valley Internationalization and Localization Special Interest Group of the Society of Technical Communication, presentation by Nancy Rains (JavaSoft, Cupertino, CA on 9 December, 1999).
  2. A Practical Guide to Software Localization, Bert Esselink (John Benjamins Publishing Company, 1998). ISBN 1556197438; $30.
  3. Guide to Macintosh Software Localization, Apple Computer (Addison-Wesley Publishing Company, 1992). ISBN 020160856160856; $24.95.
  4. "Writing for a Global Audience", SimulTrans, L.L.C., 1998 (10-page article).
  5. Technical Publications Handbook, Version 1.0, Pure Atria, 1996.
  6. "Tips for Writing Globally", Dovie Wylie, MultiLingual Computing & Technology (Vol 9, Issue 6), pp. 40-41.
    NOTE: Dovie R. Wylie, Ph.D. runs On-Site English, a training/consulting firm that teaches localization guidelines to technical writers for clients such as Oracle. Phone: 650 855-9928; Email: dovie@on-site-english.com
  7. International Technical Communication: How to Export Information About High Technology, Nancy Hoft (Wiley), 1995.  $31. ISBN: 0471037435