Chapter 8
Punctuation and Capitalization
Introduction
Punctuation and Capitalization as Syntactic Cues
Punctuation and Translation Memory
8.1 Ampersands
8.2 Colons
8.3 Commas
8.3.1 Use commas to prevent misreading
8.3.2 Use commas to separate main clauses
8.3.3 Consider using a comma before because
8.3.4 Consider using a comma before such as
8.4 Double Hyphens
8.5 Em Dashes
8.5.1 Whenever possible, use a separate sentence instead
8.5.2 Consider other ways of eliminating em dashes
8.5.3 Make sure the sentence would be grammatical if the em dash phrase were omitted
8.5.4 Don’t use em dashes as a formatting device
8.5.5 Don’t use em dashes to set off cross-references
8.5.6 Don’t use em dashes to set off definitions
8.5.7 Don’t use em dashes to set off examples
8.5.8 Don’t use em dashes to set off non-restrictive relative clauses
8.5.9 Don’t use an em dash to introduce a complete sentence
8.5.10 Don’t use an em dash to introduce an -ING phrase
8.5.11 Approved uses for em dashes
8.6 Equal Signs
8.7 Hyphens
8.7.1 Consider hyphenating noun phrases
8.7.2 Use hyphens consistently in the noun and adjective forms of multi-word verbs
8.8 Parentheses
8.8.1 Make sure readers can understand what parentheses are intended to indicate
8.8.2 Make parenthetical information grammatically independent
8.8.3 Whenever possible, put parenthetical information in a separate sentence
8.8.4 Eliminate unnecessary parentheses
8.8.5 Eliminate parenthetical comments that impede readability
8.8.6 Don’t use (s) to form plural nouns
8.8.7 Approved uses for parentheses
8.9 Quotation Marks
8.9.1 Don’t use quotation marks to represent inches or feet
8.9.2 Don’t use quotation marks for metaphors
8.9.3 Don’t use quotation marks for technical terms
8.10 Semicolons
8.10.1 Don’t use semicolons to separate clauses
8.10.2 When necessary, use semicolons to separate items in a series
8.11 Slash
8.11.1 Submit unavoidable joined terms to your localization coordinator
8.11.2 Use or instead
8.11.3 Separate the joined terms with and or with a comma
8.11.4 Eliminate unnecessary synonyms
8.12 Slash Used in and/or
8.12.1 Use a, b, or both
8.12.2 Use any of the following or one or more of the following
8.12.3 Use only or or only and
8.12.4 Revise more substantially
8.13 Capitalization
8.13.1 Capitalize proper nouns
8.13.2 Capitalize user-interface labels as they are capitalized in the interface
8.13.3 Don’t capitalize common nouns
8.13.4 When necessary, use capitalization to improve readability
8.13.5 Establish clear lines of communication with localization coordinators
Recommended Reading
Introduction
In Global English, most of the guidelines for punctuation and capitalization are the same as the guidelines in conventional style guides such as The Chicago Manual of Style. However, conventional style guides don’t take the needs of non-native speakers and translators into account. They have been written with the assumption that native speakers are the authors and the readers. Therefore, the guidelines in this chapter are intended to supplement (or, in a few cases, override) the standard rules of American English punctuation and capitalization.
|
Note: |
Strictly speaking, ampersands and equal signs are not punctuation marks. However, in this context, making the appropriate distinctions would interfere with clear communication. |
Punctuation and Capitalization as Syntactic Cues
Like other syntactic cues, punctuation marks and capitalization help readers analyze and interpret sentences correctly. Notice how much more difficult it is to read the version of this paragraph that lacks these important syntactic cues:
|
▶ |
warning charge circuit timeout indicates that the charging period has exceeded 30 seconds the charge circuit is still active please inform your support representative if this device status indicator occurs immediate replacement is recommended. |
|
▶ |
Warning: Charge Circuit Timeout |
A sentence can be more difficult to read and comprehend even if only one punctuation mark or capital letter is missing. In the following sentence, even the conventional rules of punctuation call for a comma between the main clauses.
|
|
The LET statement defines your macro variable and the macro variable references appear throughout the program statements. |
|
|
The LET statement defines your macro variable, and the macro variable references appear throughout the program statements. |
Punctuation and Translation Memory
By now you know that in addition to encouraging the use of all types of syntactic cues, Global English aims to reduce unnecessary variation in all aspects of written language. Even slight variations can make the use of translation memory (TM) less effective. For example, consider the following scenario.
The following sentence was previously translated, so the English sentence and its translation are stored as a translation pair in a TM database:
|
▶ |
Click Cancel to return to the program and correct the error. |
Later, a translator who is using the TM database encounters the following sentence:
|
▶ |
Click Cancel to return to the program, and correct the error. |
The TM software flags this sentence as a fuzzy match. That is, it displays the previous sentence alongside the new one, highlights the comma in the new sentence, and displays the translation of the previous sentence. The translator compares the two sentences and determines whether the previous translation can also be used for the new sentence.
Even if the sentences are nearly an exact match, you pay the translator a certain amount per word for translating fuzzy matches. Thus, you incur a cost for every unnecessary variation. And you incur that cost not once, but for each language that your document is translated into.
Translators sometimes examine exact matches, too, if their TM database contains documents from different product areas or domains. (Sometimes the same sentence must be translated differently in different contexts.) However, comparing fuzzy matches takes the translator more time, and you pay more for that extra time and effort.
In addition, sometimes a difference in punctuation makes a subtle difference in meaning that the translator could easily overlook. In the following example, correct should be translated as an infinitive in the first sentence and as an imperative verb in the second: 1
|
▶ |
Click Cancel to return to the program and [to] correct the error. |
|
▶ |
Click Cancel to return to the program, and correct the error. |
In other words, the first version implies that the single action of clicking Cancel has two consequences:
|
■ |
The user is returned to the program. |
|
■ |
The error is corrected. |
The second version makes it clear that correcting the error is a separate action that the user must perform.
Sometimes a slight difference in punctuation can even prevent TM software from recognizing two nearly identical sentences as fuzzy matches. In order to understand this, you need to understand how TM software divides texts into translation segments.
Most TM software uses the following punctuation marks as segment boundaries:
- periods
- question marks
- exclamation points
- semicolons
- colons
Translators can modify the segmentation rules, but these are the typical defaults. Since the following sentence contains only one of these segment boundaries (the period at the end), it constitutes a single translation segment:
|
▶ |
Every form has a current lock state—either locked or unlocked. |
By contrast, the following sentence contains two translation segments, because both the colon and the period are segment boundaries.
|
▶ |
Every form has a current lock state: either locked or unlocked. |
The difference in segmentation prevents TM software from identifying these two sentences as a fuzzy match, even though the only difference is that one has an em dash where the other has a colon.
As the following guidelines illustrate, there are many contexts in which most authors would consider either of two punctuation marks to be correct. An understanding of TM segmentation is often necessary in order to decide which punctuation mark to standardize on in those contexts.
8.1 Ampersands
Don’t use an ampersand in place of the word and. This usage is a source of unnecessary variation. In addition, some non-native speakers are not familiar with this use of the ampersand.
|
|
Use the Target Periods & Sources page to specify the source of data for each target period in the selected cycle. |
|
|
Use the Target Periods and Sources page to specify the source of data for each target period in the selected cycle. |
|
|
For more information, see Ch 14 & Ch 15. |
|
|
For more information, see chapters 14 and 15. |
Of course, it is OK to use an ampersand to refer to itself:
|
|
Special characters such as &, < , and > are not allowed. |
|
|
Note that & is replaced with the & character entity, and the entire URL is enclosed in single quotation marks. |
8.2 Colons
In a sentence that introduces multiple possibilities, use an em dash rather than a colon:
|
|
Every form has a current lock state: either locked or unlocked. |
|
|
Every form has a current lock state—either locked or unlocked. |
In this context, most authors would find either a colon or an em dash acceptable. However, if you use a colon, then TM software typically treats the adjectives that follow the colon as a separate translation segment. (See “119 and Translation Memory” on page 164.)
It is better for adjectives to be in the same translation segment as the nouns that they modify, because, in many languages, the adjectives must agree in number and gender with the nouns. For example, the French translations for locked and unlocked are slightly different depending on whether the noun that they modify is masculine or feminine:
|
|
There are two types of files: locked and unlocked. |
|
|
Il y a deux sortes de fichiers: verrouillés et déverrouillés. |
|
|
There are two types of bank vaults: locked and unlocked. |
|
|
Il y a deux sortes de chambres fortes: verrouillées et déverrouillées. |
In other cases, an adjective might have several translations, depending on the noun that it modifies. For example, deep might well be translated differently when it modifies water than when it modifies discounts or neuroses.
Alternatively, you could use a colon but repeat the noun that is being modified:
|
▶ |
There are two types of files: locked files and unlocked files. |
This is the best approach if you are using machine-translation software. Otherwise, the additional words increase the cost of translation without providing any benefit.
8.3 Commas
8.3.1 Use commas to prevent misreading
Always use a comma if the comma will prevent misreading or will make the sentence structure clearer. Consider the following sentence:
|
|
To develop an embryo needs the kind of lining that only the uterus has. |
Many readers are initially confused by this sentence, because a sentence that begins with an infinitive (in this case, To develop) often introduces a procedure, as in the following example:
|
▶ |
To develop an embryo, follow these steps: |
By inserting a comma following the infinitive, you can make it clear that the original sentence doesn’t follow that pattern:
|
|
To develop, an embryo needs the kind of lining that only the uterus has. |
8.3.2 Use commas to separate main clauses
This is a standard rule of English punctuation. However, many authors don’t follow it consistently. For example, they might fail to recognize main clauses in contexts like the following:
|
■ |
clauses that have subjectless imperative verbs:
|
|
■ |
clauses that are framed by either . . . or:
|
8.3.3 Consider using a comma before because
All style guides agree that when a subordinate clause occurs at the beginning of a sentence, it should be separated from the main clause by a comma:
|
▶ |
Because we are now able to confirm your order as soon as it is received, your credit card charge will be processed immediately. |
Most authors don’t precede a because clause with a comma when it follows the main clause. But sometimes the comma is necessary in order to prevent misreading, misinterpretation, or confusion.
To make sure your meaning is clear, follow these guidelines:
|
■ |
Use a comma before because when the clause that it introduces is not essential to your meaning. For example, if you omitted the because clause from the following sentence, you would have You do not need to specify delimiters. This is the main proposition of the sentence. The because clause merely adds an explanation.
|
|
■ |
Don’t use a comma before because if the because clause is essential to the meaning. If you omitted the because clause from the first sentence in the following example, you would have Don’t use syntactic cues. But the second sentence in the example makes it clear that that is not what the author is saying at all.
|
|
■ |
Omit the comma if the because clause doesn’t modify the entire preceding clause. In this example, the because clause explains why the interface is useful. In other words, it modifies that is useful, not the entire main clause.
|
|
Similarities between Because Clauses and Relative Clauses|
■ |
A restrictive relative clause provides essential information. No comma is used with a restrictive clause like the following:
|
|
■ |
A non-restrictive clause provides non-essential information. A non-restrictive relative clause begins with the relative pronoun which, who, whom, or whose and is preceded by a comma:
|
As you can see, with relative clauses as well as because clauses, the meaning changes depending on whether the clause is restrictive or non-restrictive. The first sentence above implies that not all butterfly taxa have a low risk of extinction. The second sentence implies that they all do.
8.3.4 Consider using a comma before such as
In guideline 8.3.3 you saw that the presence or absence of a comma affects the meaning of because clauses and relative clauses. The same is true of phrases that begin with such as.
In the following sentence, the lack of a comma implies that webEIS documents are a type of Java applet:
|
|
The JAR file format aggregates the files that are associated with Java applets such as webEIS documents. |
That interpretation is incorrect. In the following revision, the comma makes it clear that webEIS documents are a type of file that is associated with Java applets:
|
|
The JAR file format aggregates the files that are associated with Java applets, such as webEIS documents. |
In other words, the comma makes it clear that such as webEIS documents modifies the files that are associated with Java applets, not just Java applets.
Here is an explanation of how to determine whether a comma is needed:
|
■ |
If a such as phrase modifies only the closest preceding noun phrase, then don’t precede such as with a comma.
|
|
■ |
If a such as phrase modifies more than just the closest preceding noun phrase (for example, a noun phrase plus a prepositional phrase or a noun phrase plus a relative clause), then precede such as with a comma.
|
Follow this guideline even if the such as phrase occurs somewhere other than at the end of the sentence, as in this example:
|
|
Most time-series analysis tasks assume that the observations are taken at equally spaced time intervals and that no time intervals are missing. Thus, a periodic series such as transaction data must be converted into periodic data before it is analyzed. [transaction data is an example of a periodic series, so no comma is needed] |
8.4 Double Hyphens
Double hyphens are a relic from the days of typewriters. Don’t use them in documents that are produced electronically. Aside from causing unnecessary inconsistency, double hyphens sometimes interfere with the use of language technologies such as controlled-authoring software.
Often you can use an em dash in place of a double hyphen. (See the next section for guidelines on the use of em dashes.) Some authoring tools can be set up to automatically convert double hyphens to em dashes. Alternatively, in Windows applications you can insert an em dash by holding down the Alt key and then pressing 0151 on the numeric keypad. On a Macintosh, hold down the Option key, and then press the hyphen key.
8.5 Em Dashes
In this section, guidelines 8.5.4–8.5.10 are aimed at eliminating unnecessary inconsistencies. There is nothing inherently wrong with using em dashes in the contexts that those guidelines describe. However, if you and your colleagues sometimes use em dashes and other times use parentheses to set off the same type of information, then your inconsistency will interfere with the efficient use of translation memory.
Guideline 8.5.11 lists some approved uses for em dashes.
8.5.1 Whenever possible, use a separate sentence instead
If a connector such as that is, for example, or however introduces a main clause or a subordinate clause that is followed by a main clause, then start a new sentence instead of using an em dash as a separator. Putting part of a long sentence into a separate sentence makes the use of translation memory and machine translation more efficient.
|
|
A template is a single graphics element that you can resize, move, and delete—that is, you cannot manipulate any part of the template separately, since it is only a placeholder for the actual graph. |
|
|
A template is a single graphics element that you can resize, move, and delete. That is, you cannot manipulate any part of the template separately, since it is only a placeholder for the actual graph. |
|
|
If all applications store client address information in an address object and a change is needed in how this information is stored—for example, to store the street address, the city and state, and the country in three separate fields instead of one—then the change is easy to identify, make, and propagate. |
|
|
If all applications store client address information in an address object and a change is needed in how this information is stored, then the change is easy to identify, make, and propagate. For example, you can easily store the street address, the city and state, and the country in three separate fields instead of one. |
8.5.2 Consider other ways of eliminating em dashes
|
|
The fastest way to finish your configuration of the system—and the safest way—is to run the scripts that the instructions.html file refers to. |
|
|
The fastest and safest way to finish your configuration of the system is to run the scripts that the instructions.html file refers to. |
|
|
The order shown in the preceding list—although not required—is a good order in which to install these products because there are some dependencies. |
|
|
Because there are some dependencies, you should install these products in the order shown above. |
8.5.3 Make sure the sentence would be grammatical if the em dash phrase were omitted
The first version of the following sentence is ungrammatical because the verb are doesn’t agree in number with the subject SLI region type:
|
|
For the DATA step interface, the SLI region type—and hence, the SLICWTO, SLIREAD, and CICSID options—are no longer supported. |
|
|
For the DATA step interface, the SLI region type—and hence, the SLICWTO, SLIREAD, and CICSID options—is no longer supported. |
8.5.4 Don’t use em dashes as a formatting device
In the following example, either a definition list or a hanging list would be appropriate:
|
|
Analysis tab — contains functionality for calculating risk. |
|
|
Analysis tab |
|
|
Analysis tab |
In the next example, either a simple table or a block list should be used:
|
|
Some common commands include M — moves a line of text, C — copies a line of text, D — deletes a line of text, I — inserts a line of text. |
|
|
Here are some common commands:
|
8.5.5 Don’t use em dashes to set off cross-references
Use parentheses, not em dashes, to set off cross-references.
|
|
Follow the same steps that you follow to upgrade a system in place—see Upgrading in Place—with the following caveat: |
|
|
Follow the same steps that you follow to upgrade a system in place (see Upgrading in Place), with the following caveat: |
|
|
When you configure the User Service—as described in the next section—you are asked to specify an administrator. |
|
|
When you configure the User Service (as described in the next section), you are asked to specify an administrator. |
8.5.6 Don’t use em dashes to set off definitions
Use parentheses, not em dashes, to set off definitions.
|
|
The wizard uses the selected tables to generate a transformation template—a process flow diagram that includes drop zones for metadata objects. |
|
|
The wizard uses the selected tables to generate a transformation template (a process flow diagram that includes drop zones for metadata objects). |
|
|
The chart vertices—the points where the statistical values intersect the spokes—are based on the frequencies that are associated with the levels of a single numeric variable. |
|
|
The chart vertices (the points where the statistical values intersect the spokes) are based on the frequencies that are associated with the levels of a single numeric variable. |
8.5.7 Don’t use em dashes to set off examples
Use parentheses, not em dashes, to set off examples.
|
|
If you expect to use a graph over and over again—a company logo, for example—then link to it so that you can make future changes in only one place. |
|
|
If you expect to use a graph over and over again (a company logo, for example), then link to it so that you can make future changes in only one place. |
|
|
Objects can be visual objects that you place on the frame—for example, icons, push buttons, or check boxes. |
|
|
Objects can be visual objects that you place on the frame (for example, icons, push buttons, or check boxes). |
Keep in mind that examples are often introduced by such as:
|
|
Some of the tabs—such as the tabs for Notes, Support, and Process—appear only if you have defined metadata for those tabs. |
|
|
Some of the tabs (such as the tabs for Notes, Support, and Process) appear only if you have defined metadata for those tabs. |
8.5.8 Don’t use em dashes to set off non-restrictive relative clauses
If possible, put non-restrictive relative clauses into separate sentences.
|
|
Because stored process servers support MultiBridge connections—which means that an object spawner can send requests to any one of a set of multi-user server processes—it is possible to implement load balancing on a single host. |
|
|
Because stored process servers support MultiBridge connections, an object spawner can send requests to any one of a set of multi-user server processes. Therefore, it is possible to implement load balancing on a single host. |
8.5.9 Don’t use an em dash to introduce a complete sentence
Use a colon or a period, not an em dash, to introduce a complete sentence.
|
|
If you are a Finance Adjuster, then you can use all the features of the Models workspace, with one exception—you cannot create or edit unbalanced manual adjustments. |
|
|
If you are a Finance Adjuster, then you can use all the features of the Models workspace, with one exception: you cannot create or edit unbalanced manual adjustments. |
|
|
You can store the autocall macros in as many libraries as you want—but each time you call a macro, each library is searched sequentially until the macro is found. |
|
|
You can store the autocall macros in as many libraries as you want. However, each time you call a macro, each library is searched sequentially until the macro is found. |
|
|
You can view the resulting PNG files in any browser—neither Java nor ActiveX is required. |
|
|
You can view the resulting PNG files in any browser. Neither Java nor ActiveX is required. |
8.5.10 Don’t use an em dash to introduce an -ING phrase
Use a comma, not an em dash, to introduce an -ING phrase.
|
|
ActiveX draws each part of the step—resulting in a somewhat different graph. |
|
|
ActiveX draws each part of the step, resulting in a somewhat different graph. |
See guideline 7.4, “Punctuate -ING phrases correctly,” for additional examples.
8.5.11 Approved uses for em dashes
Emphasis
|
|
A J2EE enterprise application uses other technologies—in particular, Enterprise JavaBeans—in addition to Java servlet technology. |
|
|
All processing is supported for tables—if the engine that is defined in the metadata supports that processing. |
Enumerations
|
|
In the following display, three MIME types—ABC, ACGI, and AIP—are counted as page views. |
|
|
The second request—a GetMetadata method call—retrieves the columns that you defined and verifies that the column was added. |
Explanations that begin with that is
Use either em dashes or parentheses to set off explanations that begin with that is. This inconsistency is tolerated because, in this context, em dashes and parentheses have different rhetorical effects. Use em dashes for greater emphasis or for a greater break in thought. However, see also guideline 8.5.1, “Whenever possible, use a separate sentence instead.”
|
|
This problem sometimes occurs in a nested job—that is, in a loop that iterates over another loop. |
|
|
If this assumption is not true—that is, if the regressor varies systematically with the error—then ordinary regression produces inconsistent results. |
Introducing adverb phrases
|
|
The META2HTM macro is invoked twice—once before the GRAPHGEN procedure in order to specify parameters for the procedure, and a second time after the procedure to close the HTML file that was created. |
Introducing noun phrases
|
|
The TABLE OPTIONS property has a new sublist—the APPEND sublist. |
|
|
This example shows two LIBRARY statements—one statement that uses default values, and one statement that specifies all of the LIBRARY statement options. |
Introducing prepositional phrases
|
|
If the stratification variable is GENDER, then the flow loops twice—for male and for female. |
|
|
In the previous figure, information moves from the bottom up—from ODD1, to a mapping step, to the Credit data table. |
8.6 Equal Signs
Don’t use an equal sign in place of text. This usage causes unnecessary inconsistency and also causes problems for machine-translation software.
|
|
Any non-blank character = turn off metadata checking, and blank = perform metadata checking. |
|
|
Any non-blank character turns off metadata checking, and a blank character turns on metadata checking. |
|
|
GRFSRC_ returns the type of graph that the user selected, where 1 = a clickable three-dimensional graph, and 2 = a standard GIF graph. |
|
|
GRFSRC_ returns a value that indicates which type of graph the user selected:
|
However, it is OK to use equal signs to express option values in contexts like the following:
|
|
When MISSING=PAIRWISE, the calculation of the diagonal element is based on the number of non-missing observations. |
8.7 Hyphens
8.7.1 Consider hyphenating noun phrases
Hyphens can make noun phrases easier for readers to interpret correctly, and they are sometimes essential for translation.
|
|
The value in register 1 must be saved in the argument string word of the return value. |
|
|
The value in register 1 must be saved in the argument-string word of the return value. |
|
|
Site specific configuration files are typically set up by your system administrator in order to make the best use of your operating environment resources. |
|
|
Site-specific configuration files are typically set up by your system administrator in order to make the best use of your operating-environment resources. |
Some noun phrases—especially those that begin with the adjective more—have different meanings depending on whether a hyphen is used, as in these examples:
|
|
More general models might provide fewer options than more specific models. |
|
|
More-general models might provide fewer options than more-specific models. |
For additional details about clarifying the meaning of noun phrases, see guideline 3.7.2, “Consider revising noun phrases.”
8.7.2 Use hyphens consistently in the noun and adjective forms of phrasal verbs
Phrasal verbs such as back up and drop out are usually spelled as separate words when they are used as verbs. When they are used as nouns, the spelling of these words is often inconsistent: Sometimes they are spelled as one word, and other times they are hyphenated.
To eliminate such inconsistencies, follow these guidelines:
|
■ |
If the word is spelled as one word (no hyphen) when it is used as a noun, then spell the adjectival form like the noun, as in these examples: |
|
■ |
If the noun form is hyphenated, then hyphenate the adjectival form as well: |
8.8 Parentheses
8.8.1 Make sure readers can understand what parentheses are intended to indicate
Use parentheses to indicate synonyms or equivalents
Use parentheses to indicate that two terms are synonyms or that two values are equivalent, as in these examples:
|
|
You can also use the graphical user interface (GUI) to issue commands. |
|
|
Ignoring the curvature of the earth over a distance of 100 miles (161 kilometers) results in approximately 14 feet (4.3 meters) of error. |
Don’t use parentheses to indicate alternatives
As noted above, you can use parentheses to indicate that two terms are synonyms or that two values are equivalent. But don’t use parentheses to indicate that one term is an alternative to another.
The following sentence leads readers to believe that E-Plus is the new name of the company that was formerly known as Mobifunk. In reality, they are different companies.
|
|
With cellular service provided by E-Plus (Mobifunk), you can travel securely and conveniently with your own German cellular phone. |
In the following revision, the use of either . . . or makes it clear that the two companies are distinct entities:
|
|
With cellular service provided by either E-Plus or Mobifunk, you can travel securely and conveniently with your own German cellular phone. |
Don’t use an open parenthesis followed by or
Even if you use parentheses to indicate that two terms are synonyms (rather than alternatives), readers and translators won’t be sure what you mean if you precede the synonym with or. This usage is not allowed because or can imply either that the terms are synonyms or that they are alternatives. Context often is not sufficient to make the meaning clear.
Here is an example in which a parenthesis followed by or introduces ambiguity and confusion for translators and for other readers:
|
|
You can use an Explorer (or DIR) window to perform several common tasks: |
The relationship between Explorer and DIR is unclear. This sentence provides a nice segue to the next topic:
Make semantic relationships crystal clear
Even if two terms are synonyms, you can’t always rely solely on parentheses to make that semantic relationship clear. If the terms are very dissimilar, then you might need to make their relationship explicit. For example, omitting or from the previous example doesn’t resolve the confusion in readers’ minds:
|
|
You can use an Explorer (DIR) window to perform several common tasks: |
The author should explain what DIR is in a separate sentence—perhaps in a footnote:
|
|
You can use an Explorer window1 to perform several common tasks: . . . 1 In the z/OS operating environment, you can use the DIR window to perform these tasks. |
Here is another example that baffles most readers:
 |
These options cause each value in the transaction data set to generate a new result set (open cursor) from the table. |
The terms result set and open cursor are so dissimilar that you must explain their relationship before using them in this manner.2
8.8.2 Make parenthetical information grammatically independent
Parenthetical information must always be grammatically independent of the rest of the sentence. Since it is ungrammatical to pair a singular noun with a plural verb, the parentheses must be removed from these example sentences:
|
|
The table (and all rows) are dropped when the connection is closed. |
|
|
The table and all rows are dropped when the connection is closed. |
|
|
Test the server (and clients) that enable your users to schedule sets of jobs. |
|
|
Test the server and clients that enable your users to schedule sets of jobs. |
8.8.3 Whenever possible, put parenthetical information in a separate sentence
|
|
All sessions have an associated timeout value (the default is 15 minutes). |
|
|
All sessions have an associated timeout value. The default is 15 minutes. |
|
|
The Arrange item aligns the icons for the data objects (in multiple rows, if needed). |
|
|
The Arrange item aligns the icons for the data objects. If necessary, the icons are arranged in multiple rows. |
|
|
The entries in the list might be descriptive, such as Server, or they might be actual host names (in custom plans). |
|
|
The entries in the list might be descriptive, such as Server. In custom plans, the entries might be actual host names. |
|
|
Use this window to add additional types of SAS servers (consisting of a logical server and a corresponding physical server) to the main server definition. |
|
|
Use this window to add additional types of SAS servers to the main server definition. Each SAS server consists of a logical server and a corresponding physical server. |
|
|
A Leaf members formula determines the values for all locations that are designated by the formula-bearing member (which must be a leaf member), as well as the values of leaf members for all other dimensions. |
|
|
A Leaf members formula determines the values for all locations that are designated by the formula-bearing member, as well as the values of leaf members for all other dimensions. The formula-bearing member must be a leaf member. |
8.8.4 Eliminate unnecessary parentheses
If parentheses don’t make a sentence more concise or more readable, and if the information that they contain is not clearly parenthetical, then they are simply intrusive.
|
|
If you specify an output data set, then all the variables from the input address data set are copied to the output data set (and the new variables are added). |
|
|
If you specify an output data set, then all the variables from the input address data set are copied to the output data set, and the new variables are added. |
|
|
Prompting enables you to set more options than you can set when you connect directly to the provider (instead of using OLE DB Services). |
|
|
Prompting enables you to set more options than you can set when you connect directly to the provider instead of using OLE DB Services. |
|
|
Use the Class Settings window to specify whether a class (and its objects) can use the Properties window, a custom attributes window, or both, for setting properties. |
|
|
Use the Class Settings window to specify whether a class and its objects can use the Properties window, a custom attributes window, or both, for setting properties. |
8.8.5 Eliminate parenthetical comments that impede readability
Parentheses often enable an author to add information to a sentence concisely without making the sentence structure excessively complicated. For example, both versions of the following sentence are correct, but the second is more concise, easier to read, and hence easier and less expensive to translate:
|
|
The FORMULA= option is typically used to create formula variables in the output data view. If you also specify the OUTDATA= option, then you can also create derived variables in the output data set. [34 words] |
|
|
The FORMULA= option is typically used to create formula variables in the output data view (and to create derived variables in the output data set, if OUTDATA= is specified). [29 words] |
But in the following example, parentheses were used to cram so much information into the sentence that the sentence is difficult to comprehend and translate:
|
|
The program sets the values of items in the view descriptor (that is, only the selected items in the same record) to blanks and removes the lowest-level data record from the database. |
Untangle the ideas and put them into separate sentences instead:
|
|
When the selected items are in the same record, the program sets the values of those items in the view descriptor to blanks. The program also removes the lowest-level data record from the database. |
8.8.6 Don’t use (s) to form plural nouns
In English, (s) is commonly used to indicate that the reader should interpret a noun as either singular or plural:
|
|
Check the error(s) in the log file. |
However, in most languages, you cannot make a noun plural simply by adding a suffix to it. Therefore, the noun that ends in (s) often is not directly translatable. The (s) forces translators to make a choice between the singular and plural interpretation or to revise the sentence substantially. When a document is being translated into several languages, each translator must spend extra time deciding what to do about (s).
You can eliminate (s) constructions by using the revision strategies described below.
|
|
▶ |
Are you sure you want to delete the file(s)? |
|
|
Möchten Sie die Datei(en) wirklich löschen? |
You can also do it in French sometimes. However, French articles, adjectives, participles, and pronouns must agree in gender and number with the nouns that they modify or refer to. Thus, a single instance of (s) in English can proliferate to many instances in the French translation:
▶ |
The file(s) referenced in the stored process must be created and maintained by someone who has Write access to the files’ locations on the system. |
|
|
Le(s) fichier(s) référencé(s) dans l’application stockée doit(vent) être créé(s) et actualisé(s) par un utilisateur ayant un accès en écriture à l’emplacement des fichiers sur le système. |
Translators have various strategies for dealing with (s), but many of those strategies (like the one above) are awkward and unpleasant. You wouldn’t want to see comparable strategies used in English, so why impose them on readers of your translated documentation? Use the following revision strategies to eliminate (s) instead.
Use each, every, or any of
|
|
Return the column(s) to their original position(s): |
|
|
Return each column to its original position: |
|
|
The file(s) that are referenced in the stored process must be created and maintained by someone who has Write access to the files’ locations on the system. |
|
|
Every file that is referenced in the stored process must be created and maintained by someone who has Write access to the file’s location on the system. |
|
|
When the EFI encounters the specified character(s) in the external file, it recognizes them as special missing values. |
|
|
When the EFI encounters any of the specified characters in the external file, it recognizes them as special missing values. |
Use one or more
|
|
You will need your installation kit(s), which contains the CDs or DVDs that you will use during the installation.3 |
|
|
You will need one or more installation kits, which contain the CDs or DVDs that you will use during the installation. |
Rearrange the sentence
|
|
Check the error(s) in the log file. |
|
|
Check the log file for errors. |
Use just the plural noun
Consider using just the plural noun. The loss of meaning usually is not significant.
|
Check the specified system error table(s), and correct the errors. |
|
|
Check the specified system error tables, and correct the errors. |
This revision strategy is often the only one that is suitable for user-interface text. In the following example, a singular noun would be misleading:
|
The Create a Job Object(s) for Scheduling dialog box contains the following fields:4 |
|
|
The Create a Job Object for Scheduling dialog box contains the following fields: |
The “one or more” approach that is used below is unnecessarily precise, considering that few users are going to pay significant attention to the title of the dialog box:
|
|
The Create One or More Job Objects for Scheduling dialog box contains the following fields: |
The world will not end if you just use the plural:
|
|
The Create Job Objects for Scheduling dialog box contains the following fields: |
Use just the singular noun
In user-interface text, if the noun can be either a mass noun or a countable noun, then consider using the singular:
|
On the Confirm Deletion(s) page, answer the following prompts: |
|
|
On the Confirm Deletion page, answer the following prompts: |
Use <singular noun> or <plural noun>
Sometimes you can use <singular noun> or <plural noun> instead of (s), as in these examples:
|
Select the year(s) for which the report will be generated. |
|
|
Select the year or years for which the report will be generated. |
|
If you have several SID files, you might want to rename the SID file so that it is clear which machine(s) the SID file is for. |
|
|
If you have several SID files, you might want to rename the SID file so that it is clear which machine or machines the SID file is for. |
However, often this is not the best revision strategy. Always consider using one of the other revision strategies instead.
|
Select the item(s) that you want to remove. |
|
|
Select the item or items that you want to remove. |
|
|
Select the items that you want to remove. |
|
Use the administration tool to create the appropriate group folder(s) for the content. |
|
|
Use the administration tool to create the appropriate group folder or folders for the content. |
|
|
Use the administration tool to create one or more group folders for the content. |
|
|
▶ |
{0} scenario(s) were deleted. |
In German, the translation is different if {0} is replaced by 1 than it is if {0} is replaced by 0 or by any other number:
|
|
1 Szenario ist gelöscht worden. |
|
|
0 Szenarien sind gelöscht worden. |
|
|
2 Szenarien sind gelöscht worden. |
In Russian and other Slavic languages, the translations are different depending on whether there are no scenarios, 1 scenario, 2-4 scenarios, or 5 or more scenarios:
|
|
0 сценарии были удалены. |
|
|
1 сценарий был удален. |
|
|
2 сценария были удалены. |
|
|
5 сценариев были удалены. |
The German translators would probably have to choose a translation like this:
|
|
{0} Szenario/Szenarien ist/sind gelöscht worden. |
The Russian translator would probably have to choose a translation like this:
|
|
{0} сценарии/сценарий/сценария/сценариев был/были удален/удалены. |
How readable is the English equivalent of the Russian translation?
|
▶ |
{0} scenarios/scenario/scenarios/scenarios was/were deleted/deleted. |
(continued)
|
Instead of using file(s), the software developer should implement separate software messages to account for differences in singulars and plurals. If you separate the number of scenarios from the rest of the sentence structure, then even for Russian you might need only two separate messages:
|
8.8.7 Approved uses for parentheses
Acronyms
Use parentheses for including an acronym or some other short form of a term after the full form of a term. Also use parentheses for including the full form of a term after an acronym.
|
|
A SAS package file (SPK file) is a container file. |
|
|
Instead of creating an entry for each user, you can create an LDIF (Lightweight Directory Interchange Format) file. |
Concise Alternatives to Separate, Complete Sentences
Use parentheses to enclose concise phrases that you would otherwise have to put in separate sentences.
|
|
A value of 1 (the default) specifies to compare only identities with which an ExternalIdentity object is associated. |
|
|
(optional) Add a background image to the banner. |
Cross-references
Use parentheses to enclose cross-references.
|
|
After verifying that users can connect to the metadata server (as described in Connecting to SAS Servers), make sure that they can access the data sources as well. |
For consistency, when a cross-reference occurs at the end of a sentence, always place it in a separate sentence.
|
The user login functions as an inbound login (see Important Security Terms). |
|
|
The user login functions as an inbound login. (See Important Security Terms.) |
|
A LAYOUT LATTICE enables you to display a sidebar between a header and an axis (see the first figure for LAYOUT LATTICE). |
|
|
A LAYOUT LATTICE enables you to display a sidebar between a header and an axis. (See the first figure for LAYOUT LATTICE.) |
Definitions
Use parentheses to enclose definitions of terms.
|
|
A J2EE Web application is delivered as a WAR file (an aggregate file that contains all of the files that make up the application). |
Examples
If you need to set off examples from the rest of the sentence, then use parentheses rather than em dashes.
|
|
Members of the Portal Admin group (for example, the SAS Web Administrator) are automatically designated as group content administrators for all groups. |
|
|
A class describes an object’s characteristics (such as attributes or instance variables), as well as the operations that the object can perform. |
|
|
Area features represent two-dimensional entities such as geographic areas (countries, states, and so on) or floor plans for buildings. |
|
|
A Grid layout is commonly used to position a text entry (title, footnote, or legend) outside the graph area. |
Explanations
Use parentheses to enclose most types of explanations.
|
|
A left outer join lists matching rows and rows from the left-hand table (the first table listed in the FROM clause) that do not match any row in the right-hand table (the second table listed in the FROM clause). |
|
|
Filters are evaluated based on the data type (character or numeric) of the selected data item and the locale that is currently active for the browser. |
|
|
A copy of the log is stored in the My Documents folder (on Windows) or in your home directory (on UNIX). |
|
|
An optional _WAIT parameter can be used to specify a maximum wait time (in seconds) for any sessions to expire. |
Explanations that begin with that is
Use either em dashes or parentheses to set off explanations that begin with that is. This inconsistency is tolerated because, in this context, em dashes and parentheses have different rhetorical effects. Use em dashes for greater emphasis or for a greater break in thought. However, see also guideline 8.8.3, “Whenever possible, put parenthetical information in a separate sentence.”
|
|
An object cannot receive a _refresh method unless it is completely initialized (that is, unless the object’s _init and _postInit methods have run). |
Special characters or punctuation marks
Technical documentation sometimes contains references to special characters or punctuation marks. The characters are often enclosed in parentheses, as in these examples:
|
|
Special characters generally are not allowed. However, in aliases you can use the dollar sign ($), the pound sign (#), and the at sign (@). |
|
|
Numeric missing values are represented by a single decimal point (.). |
It probably is not necessary to show readers what periods and commas look like—although periods are referred to as full stops in some varieties of English. However, for other characters and punctuation marks, this convention is appropriate for a global audience. Non-native speakers might not recognize the names of characters such as tildes (~) and asterisks (*). In addition, some of these marks are not the same for all languages. For example, the appearance and usage of quotation marks varies significantly around the world, and in Danish, the English division sign (÷) is used to indicate subtraction.
Synonyms or equivalents
|
|
You can use the customer demo (custdemo) account to test the authentication. |
|
|
Users can drill down to a map of Wake County (MAPS.WAKE.TRACT) by selecting Wake County and running the DRILL action. |
8.9 Quotation Marks
8.9.1 Don’t use quotation marks to represent inches or feet
Many readers in countries that use the metric system do not understand the meaning of quotation marks that are used for this purpose. Also consider including the metric equivalents of English measurements.
|
|
By default, the shadow extends 1/16” to the right and 1/16” below the legend. |
|
|
By default, the shadow extends 1/16th of an inch to the right and 1/16th of an inch below the legend. |
|
|
Ignoring the curvature of the earth over a distance of 100 miles results in approximately 14’ of error. |
|
|
Ignoring the curvature of the earth over a distance of 100 miles (161 kilometers) results in approximately 14 feet (4.3 meters) of error. |
8.9.2 Don’t use quotation marks for metaphors
Don’t use quotation marks to indicate that a term is being used in a metaphorical sense. Non-native speakers might not understand such terms, and it might be difficult for translators to express the metaphor in other languages. Replace the metaphor with literal language.
|
|
If you invoke the Import wizard on a PC that contains an ATI XCEL128 video card, the PC might “freeze.” |
|
|
If you invoke the Import wizard on a PC that contains an ATI XCEL128 video card, the PC might stop responding to input. |
8.9.3 Don’t use quotation marks for technical terms
Don’t enclose a term in quotation marks merely because it is being used in a specialized or technical sense.
|
|
The Foundation repository is a “master” repository on which other repositories rely for shared information. |
|
|
The Foundation repository is a master repository on which other repositories rely for shared information. |
8.10 Semicolons
8.10.1 Don’t use semicolons to separate clauses
Some authors use semicolons extensively as clause separators, but most do not. Therefore, this use of semicolons contributes to unnecessary variation.
Because semicolons are not followed by capital letters, they blend in with the surrounding text. They can make already-long sentences seem exceptionally long and intimidating, as in this example:
|
|
The Calendar 1 has a holiday on Sunday; on Monday and Tuesday work is done from 7:00 a.m. to 11:00 a.m. and from 12:00 noon to 4:00 p.m.; on Friday work is done from 12:00 (midnight) to 8:00 a.m.; on Saturday work is done from 7:00 a.m. to 11:00 a.m.; on other days work is done from 9:00 a.m. to 5:00 p.m., as defined by the default calendar. repository is a “master” repository on which other repositories rely for shared information. |
In this case, most technical writers would put the information in an unordered list even if they were not writing for a global audience:
|
|
Calendar 1 has the following characteristics:
|
In technical documentation there is seldom a significant difference in the rhetorical effect of semicolons and periods when they are used as clause separators. In particular, when the second clause starts with a logical connector such as that is, for example, or however, the difference in the rhetorical effect is negligible:
|
|
Because the user ID is a trusted ID, servers such as the OLAP server, object spawner, and mid-tier applications can use this ID to impersonate authenticated clients on the metadata server; that is, the servers can communicate with the metadata server on behalf of the clients. |
|
|
Because the user ID is a trusted ID, servers such as the OLAP server, object spawner, and mid-tier applications can use this ID to impersonate authenticated clients on the metadata server. That is, the servers can communicate with the metadata server on behalf of the clients. |
|
|
Objects can also be nonvisual objects that manage the application behind the scenes; for example, an object that enables you to interact with data might not have a visual representation, but it can still enable you to access variables, add data, or delete data. |
|
|
Objects can also be nonvisual objects that manage the application behind the scenes. For example, an object that enables you to interact with data might not have a visual representation, but it can still enable you to access variables, add data, or delete data. |
Even when no logical connector is present, the rhetorical difference between a semicolon and a period is usually insignificant:
|
|
Only activities that have actual start times are assumed to have started; all other activities have an implicit start time that is greater than or equal to TIMENOW. |
|
|
Only activities that have actual start times are assumed to have started. All other activities have an implicit start time that is greater than or equal to TIMENOW. |
8.10.2 When necessary, use semicolons to separate items in a series
Although you should not use semicolons as clause separators, Global English doesn’t impose any other extraordinary restrictions on the use of semicolons. For example, when one or more items in a series includes a comma, you can use semicolons to separate the items:
|
|
Packages can contain SAS files (SAS catalogs; SAS data sets; various types of SAS databases, including cubes; and SAS SQL views), binary files, HTML files, reference strings, text files, and viewer files. |
In this context, semicolons are useful syntactic cues that help prevent misreading.
Sometimes semicolons are also useful for clarifying which items in a series a prepositional phrase or relative clause is modifying. See guideline 4.3, “Clarify what each relative clause is modifying,” for an example.
8.11 Slash
In general, avoid using slashes to join two or more words. This construction can be difficult to translate. It doesn’t have the same meaning in all contexts, and translators sometimes cannot determine what you mean.
For example, in the following sentences, it is not clear whether the terms that are joined by slashes are synonyms or whether they are alternatives to each other:
|
|
The following example shows how to move a folder that contains publication/subscription content: |
|
|
If any entry type is ‘ALL’, then all entries/variables will be displayed regardless of type. |
In the next example, it is not clear whether COM/DCOM represents a single entity or what the relationship is between the two acronyms:
|
|
This application programming interface (API) provides access to the server from a variety of programming environments, including Java, COM/DCOM, and SAS. |
On the other hand, some terms that are joined by slashes are well established in particular subject areas and should not be changed. For example, it would be absurd to change the term client/server in software documentation:
|
▶ |
A sample client/server XML log is shown below. |
In addition, it would be silly to make a change in some contexts:
|
▶ |
A Y/N switch indicates whether to allow users to use the USER= and PASSWD= options. |
The following subsections present strategies for dealing with joined terms that do need to be changed or explained.
8.11.1 Submit unavoidable joined terms to your localization coordinator
If a joined term in a document that will be translated is uncommon or is used in very specific technical contexts, then submit the term to the localization coordinator before localization begins. The localization coordinator can then ask you for explanations of any joined terms that she or he has not encountered before.
Here are some examples of joined terms that a localization coordinator would probably want to know about in advance:
|
▶ |
The Model Viewer graphically displays the interdependence of the most significant risk factors and their effects on profit/loss. |
|
▶ |
You can specify filtering criteria in the form of name/value pairs. |
|
▶ |
Interfaces help implement model/view communication by establishing a type of relationship between the model and the viewer. |
It is especially important to communicate with the localization coordinator about any joined terms that are used in a software user interface. Software localization typically begins before the documentation is localized. Therefore, when a localization coordinator encounters user-interface labels like the ones below, there is no documentation to refer to for explanations:
|
▶ |
Allow horizontal Grow/Shrink but not vertical |
|
▶ |
Offer group/subgroup |
|
▶ |
Value/CAMs |
8.11.2 Use or instead
If the joined terms are alternatives to each other, you can often separate the terms with or. However, in many contexts, if you merely replace the slash with or, you will introduce an ambiguity. You might need to use one of the revision strategies that are discussed in guideline 4.6, “Clarify ambiguous modification in conjoined noun phrases.”
In the revision of the following example, it is not clear that page modifies size:
|
|
Choosing a page/buffer size that is larger than the default can speed up execution time. |
|
|
Choosing a page or buffer size that is larger than the default can speed up execution time. |
Only the second of the following possible interpretations is correct:
|
|
Choosing a page or a buffer size that is larger than the default can speed up execution time. |
|
|
Choosing a page size or a buffer size that is larger than the default can speed up execution time. |
8.11.3 Separate the joined terms with and or with a comma
If the joined terms are alternatives to each other, you can usually just separate them with a comma. In the following example, the COM and DCOM acronyms represent separate but related standards for communication among software components:
|
|
This application programming interface provides access to the server from a variety of programming environments, including Java, COM/DCOM, and SAS. |
|
|
This application programming interface provides access to the server from a variety of programming environments, including Java, COM, DCOM, and SAS. |
If these two alternatives occur at the end of a sentence, then of course they also need to be separated by and:
|
|
This application programming interface provides access to the server from a variety of programming environments, including Java, SAS, COM, and DCOM. |
8.11.4 Eliminate unnecessary synonyms
If the joined terms are exact synonyms, consider standardizing on one term. If necessary, find an appropriate place in your document to acknowledge both terms but to explain that you are using only one of them.
If the joined terms are near synonyms, or if most of what you say about one of the terms in part of your document applies to the other term as well, then try to find a term that encompasses both of them, as in this example:
|
|
If you are creating the account on Windows, grant the Log on as a batch job permission/policy for the account on each Windows machine in the cluster. |
|
|
If you are creating the account on Windows, grant the Log on as a batch job authorization for the account on each Windows machine in the cluster. |
8.12 Slash used in and/or
The and/or construction is a special case. Unlike other joined terms, and/or is almost always clear and concise. It doesn’t pose a problem for non-native speakers or other readers, and it doesn’t pose a problem for translation into languages such as German and French.
Consult your localization coordinator before you decide to eliminate and/or from documents that will be translated. If you decide to eliminate it, then consider using one of the following revision strategies.
8.12.1 Use a, b, or both
If and/or joins two elements at the end of a sentence, consider using or both instead:
|
|
You can avoid this problem by selectively ordering the plot statements and/or by using transparency on the individual plots. |
|
|
You can avoid this problem by selectively ordering the plot statements, by using transparency on the individual plots, or both. |
|
|
To override the sequential order for filling cells, you can use the COLUMN= and/or ROW= options, which give you complete control over the fill order. |
|
|
To override the sequential order for filling cells, you can use the COLUMN= option, the ROW= option, or both. These options give you complete control over the fill order. |
8.12.2 Use any of the following or one or more of the following
If and/or joins more than two elements at the end of a sentence, consider using any of the following or one or more of the following:
|
|
You can add context-sensitive Help for components, for status-line messages, and/or for tool tips. |
|
|
You can add context-sensitive Help for any of the following items: components, status-line messages, and tool tips. |
|
|
A simple portlet displays text, data, and/or images. |
|
|
A simple portlet displays one or more of the following types of content:
|
8.12.3 Use only or or only and
If and/or joins elements that are not at the end of a sentence, then consider replacing it with just or or and. There is some loss of meaning or precision, but the loss is seldom significant:
|
|
If you have entered your user ID and/or password incorrectly, you have two more opportunities to enter the correct information. |
|
|
If you have entered your user ID or password incorrectly, you have two more opportunities to enter the correct information. |
|
|
the Add Users and/or Groups window |
|
|
the Add Users or Groups window |
|
|
Select System to review and/or select a font from available system fonts. |
|
|
Select System to review the available system fonts and to select a font. |
|
Be Careful Not to Distort Your Meaning|
|
The system administrator has not installed, configured, and/or started the WebDoc application. |
|
|
The system administrator has not installed, configured, or started the WebDoc application. |
This sentence illustrates how difficult it can be to find a suitable alternative for an and/or construction.
The following revision is unacceptable because of the sexist pronoun he:
|
|
The system administrator has not installed or configured the WebDoc application, or he has not started it. |
The next revision is OK except that it uses passive voice:
|
|
The WebDoc application has not been installed or configured, or it has not been started. |
This last revision is perhaps the most suitable for translation even though it is eight words longer than the original sentence:
|
|
Either the system administrator has not installed or configured the WebDoc application, or the system administrator has not started the application. |
8.12.4 Revise more substantially
As always, search for alternatives if the revision strategies discussed in this book are not optimal for a particular context. For example, sometimes the elements that and/or joins are not at the end of a sentence, but you can move them to the end by dividing or rearranging the sentence:
|
|
A simple portlet displays text, data, and/or images, with no interactive capabilities. |
|
|
A simple portlet displays one or more of the following types of content: text, data, images. It does not provide any interactive capabilities. |
Here is another possible revision of that sentence:
|
|
A simple portlet displays text, data, images, or any combination of the three. It does not provide any interactive capabilities. |
In the revision of the next example, parentheses were used to enclose the alternatives that were being joined by and/or:
|
|
You can specify up to four SIDEBAR blocks in a LAYOUT LATTICE—one for each of the top, bottom, left, and/or right sidebar positions. |
|
|
You can specify up to four SIDEBAR blocks in a LAYOUT LATTICE—one for each of the sidebar positions (top, bottom, left, right). |
8.13 Capitalization
The Importance of Consistent Capitalization
Capitalization is an important syntactic cue because it helps translators and other readers recognize that a term is a proper noun (name) rather than a common noun. Common nouns are virtually always translated. Names of companies and products are not translated.
Other proper nouns, such as names of major software components, might or might not be translated.5 Nevertheless, it is important to be consistent about whether you capitalize a particular term or not. Translators should be able to rely on English capitalization to help them decide whether to translate a term or not.
Here is an example of what can happen when you are inconsistent about capitalization. Suppose that in one part of a document, the term response table base name is not capitalized. A German translator translates it because it appears to be a common noun.
|
▶ |
Specify a response table base name. |
|
|
Geben Sie ein Basisname für die Response-Tabelle an. |
Elsewhere—in a related document or in a software message—the same term is capitalized:
|
▶ |
A Response Table Base Name must be specified. |
Now the translator has to determine whether the term is a proper noun or not—a time-consuming process that can require the involvement of several other individuals. In the worst-case scenario, the capitalized term is left in English in the second sentence. After all, there is no guarantee that the same translator will translate all texts or software in which the term occurs, nor that teams of translators will always be able to collaborate closely when faced with tight deadlines.
|
|
Es muss ein Response Table Base Name angegeben werden. |
Later, a user of the German version of the software needs additional information about this Response Table Base Name. But the detailed information is in a topic in which the term was translated because the English term was in lowercase. The German user somehow has to know to look for information about the Basisname für die Response-Tabelle instead of about the Response Table Base Name. How likely is the German user to find the information?
Perhaps the user will be able to get the necessary information from technical support—at additional expense to the software company, of course. But in the future, if he has a choice, he might choose to avoid such problems by buying software that was initially developed in German rather than a product that was translated from some other language.
In summary, inconsistent capitalization can have the following consequences:
|
■ |
Translators are less productive because they have to research capitalization issues. |
|
■ |
Subject-matter experts and others must spend time helping to resolve such issues. |
|
■ |
Users or readers of translated software or documentation are frustrated or confused by inconsistencies. The inconsistencies force them to contact technical support for assistance. |
|
■ |
Users’ frustrations influence their future choices of products. |
|
The guidelines in this section will help you avoid these consequences. |
8.13.1 Capitalize proper nouns
Proper nouns include all of the following:
|
■ |
trademarks |
|
■ |
product names—even if they are not trademarks |
|
■ |
major components or subsystems of a product
|
|
■ |
other names
|
|
■ |
acronyms, initialisms, and short forms of names |
8.13.2 Capitalize user-interface labels as they are capitalized in the interface
|
■ |
When documenting software or any device that has a graphical user interface, use the same capitalization that is used in the interface.
|
|
■ |
If a term refers to a capitalized user-interface label in some contexts but is used as a common noun in other contexts, then capitalize it only when it refers to the user-interface label:
|
|
■ |
Unless title-style capitalization is used for all user-interface labels, use a different font or some other typographic convention to visually distinguish the labels from the surrounding text. In the following example, the monospace font is an important syntactic cue that helps readers interpret the sentence correctly:
|
8.13.3 Don’t capitalize common nouns
In software messages, inappropriate capitalization of common nouns is rampant:
|
|
The Default Aggregation must contain all Levels in a Cube. |
|
|
The default aggregation must contain all levels in a cube. |
Sometimes this misguided convention is carried over into documentation:
|
|
The Episode Data that the device records is summarized below. |
|
|
The episode data that the device records is summarized below. |
In addition, many software developers, engineers, and other product developers regard every component or feature that they develop as being so noteworthy that it merits capitalization. As the passage of time renders their creation less special, the capitalization falls by the wayside, leading to inconsistencies.
Here are some guidelines that will help you identify and combat unwarranted capitalization:
|
■ |
If a name is followed by another noun that is not part of the name, don’t capitalize that noun:
However, note that a final noun is often regarded as part of a name:
|
|
■ |
If there can be more than one of something, then it probably is not a proper noun and should not be capitalized:
There are exceptions, but many of the exceptions are clearly geographical or geopolitical names:
|
|
■ |
Conversely, don’t assume that something is a proper noun merely because there can be only one of it in a particular context. In the following example, fact is not a name. It is merely a type of table.
|
|
■ |
The fact that an acronym or initialism exists for a term doesn’t mean that the full form of the term should be capitalized:
However, if the acronym or initialism represents a proper noun, then of course the full form should be capitalized:
|
8.13.4 When necessary, use capitalization to improve readability
Some terms should be capitalized to prevent misreading. Inform your localization coordinator that you are capitalizing these terms for that reason.
|
|
In order to extract metadata, users must have Read access to the metadata records and to the database tables. |
|
|
Do not allow Lead or Active Can electrodes to come into contact during a high-voltage therapy. |
8.13.5 Establish clear lines of communication with localization coordinators
Recognize that your localization staff often must weigh several factors in order to decide whether to translate a capitalized term or not. Make sure they know who to contact when they have questions about such issues.
Keep track of all decisions that you make regarding capitalization, and be consistent.
Recommended Reading
Meyer, Charles F. 1987. A Linguistic Study of American Punctuation. New York: Peter Lang.
1 See guideline 8.3 for contexts in which commas can make a more significant difference in meaning.
2 A corrected version of the sentence is not presented here because the topic in which the sentence was found did not include an explanation.
3 Note the conflict between the plural interpretation of kit(s) and the verb contains. This usage is a violation of guideline 8.8.2, “Make parenthetical information grammatically independent.”
4 The conflict between the singular article a and the plural interpretation of Object(s) is another violation of guideline 8.8.2. This conflict is far more disturbing than the slight loss of meaning that occurs when you make the noun plural.
5 Different cultures, and different audiences within those cultures, have different attitudes toward terms that are left in English. In one software document in which JDBC Table Viewer was used, the term was left in English in the German version of the document. In the French version of the document, the term was translated.