Localization Guidelines for Technical Communicators
| By Thomas Albert | 14 December, 1999 | talbert747@gmail.com |
Table of Contents
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
- 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"
- 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)
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:
| Key idea | ||
| Original draft | Revision | Commentary |
| 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. | ||
| 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. | |
| 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. | ||
| 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)
| 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. |
| 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' | |
| 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 |
|
| 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. |
| 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. |
| Avoid the slash inside words: "and/or", "s/he" because the translator might think you are giving a file path. |
| Use English, not Latin | ||
| e.g. i.e. via email |
for example,
that is, using email |
|
| 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 |
| 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 |
| Change "in order to" to "to" | ||
| In order to start the application … | To start the application. | |
| 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. |
| 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. |
| 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. |
| 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" |
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
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
| 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. | |
| 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. |
| 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? |
| 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". |
| 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. |
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
| 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. | |
| Think globally in your date references. | ||
| Suppose it is New Year's Day, and … | Suppose it is the first day in January, and … | |
| Think globally in your hour references. | ||
| Suppose it is 7 p.m. | Suppose it is seven o'clock in the evening | |
| 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 |
| Think globally in your numeric formats. | ||
| 12,043.47 in USA 12.043,47 (or a variant) in Europe |
||
| 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). |
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
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: