Different languages have different ways of writing; sometimes it's related to the culture. Here are some tips and conventions.
When to keep original English?
Keeping the original English doesn't necessarily mean you didn't do your job well. Instead, it simply avoids confusion for readers, because they may get better understandings from the original words.
When to keep both English and Chinese
The full name of an acronym occurs at its first time
An acronym tends to be spelled out at its first occurrence. Provide a translation for it (as possible as you can), and include the English full name and acronym in brackets. For example:
Magnolia CMS needs a Java Runtime Environment (JRE).
Magnolia CMS需要在一个Java实时环境（Java Runtime Environment，JRE）里运行。
A same Chinese translation is used for two or more English words
This happens when a fixed translation already exists for terms. For example, attribute and property both are translated as "属性" which is believed as the most proper translation. However, in Magnolia documentation, attribute and property are used in different contexts. Attribute is mostly related to HTML or FreeMarker, while property is something we configured under a node. Here is the workaround:
- If only one of them occurs on a page, then you'll be fine. Most likely the reader will figure it out.
- If the two of them appear on a same page, include the English word in brackets for each.
After activation, in the
body element in the HTML,
body id="article" class="col-subcol-subcol". The
bodyID element includes the article attribute and uses the
bodyID property assigned in the
body id="article" class="col-subcol-subcol"。
It's a fixed expression in English and used a lot in technical documents
Such expressions include "on-the-fly", "out-of-the-box", and so on. You can find a Chinese word to express the meanings, but the reader may already be familiar with the English word. Keeping them both builds a correspondence and therefore helps readers understand.
When to keep only English
It's well-known in English spelling
Code and words in special format
Code is always written in English. In Magnolia documentation, words in
monospace format are something what users see in the UI during configuration. It's safe to leave them in English.
Literal translation vs. free translation
The literal translation here is not equal to machine translation. It should at least have correct grammar and order, which is better than machine translation. In a free translation, words or phrases different from the original ones are used to express the same things.
The general idea is to use a literal translation when it's clear enough. Use free translation only when a literal translation is hard to understand or may cause confusion. Scenarios to use them have been widely discussed by translators. However, technical documentation is different from normal books and novels because it's supposed to be simple, explicit, and accurate. It has minimum (even no) idioms, rhetoric, or exaggerated emotional expressions. As a matter of fact, it's plain and dull, targeted at audience with special purposes. Therefore, we should keep the translation as easy as possible. Literal translation applies to most situations. All you have to do is to change the way of writing to make it sound local (discussed in the next section).
An example for a free translation is the word "teaser". Literally, it means someone or something that teases people, which is what the literal translation tends to be (and also has negative meanings). However, in Magnolia, it refers to the image or text on a web page that attracts the visitors to click. After discussions, we decide to use the translation for "outline (要点)".
Chinese reading habits
To make documentation sound more Chinese, we should consider Chinese reading habits.
Adverbial clauses starting with "to/in…" are usually placed before the action in a sentence in Chinese.
products content node. This adds a new tile in the app launcher.
In Chinese grammar, modifying words and phrases are always put before the modified word. Therefore Chinese doesn't have attributive clauses. However, attributive clauses are very common in English. Sometimes there are modifying clauses inside clauses, which make the sentence even more complicated. In cases like that, we split the sentences.
First, try to rewrite a long sentence into several short sentences in English, and find out the logic between. Second, translate them into Chinese, and use proper words (and/or punctuations) to connect them.
Content app is a special app type that is well suited for custom content types such as products.
内容应用是一种特殊的应用（Content app is a special app type），很适合用于定制的内容类型（It is well suited for custom content types），如产品等（such as products）。
Think of a typical corporate website. It has carefully designed branding and corporate identity: colors, fonts, images and page layout all contribute to making every page look and feel consistent and part of the whole.
试着去想象一个典型的公司网站（Think of a typical corporate website）。它会包含精心设计的品牌和公司形象（It has carefully designed branding and corporate identity）——颜色，字体，图片，以及页面布局（colors, fonts, images and page layout），使每一页给人的外观和感觉都是一致的（making every page look and feel consistent），是整体当中的一部分（and is/are part of the whole）。
Connection between sentences
English grammar is strict. A complete sentence must end with a period. Even when two sentences are logically connected, you still need to put a period between them if there are no subordinating conjunctions. However, Chinese allows the usage of a comma between two complete sentences as long as they have a logical connection. The main difference may be that Chinese tends to view the idea of a sentence as a whole. If a sentence is complete in grammar but its idea is not, then it's fine to have a parallel sentence to complete the idea. Usually a sentence with no more than three parallel sentences would be acceptable to most people.
In addition, Chinese readers like to see the logic between sentences through conjunctions. Sometimes a dash can do the work.
It is the parent container. Inside the Shell is the App Framework. The framework is like a process manager for apps; it manages the app lifecycle (start, stop, focus).
Shell是父容器（Shell is the parent container），在它里面是应用框架（Inside the Shell is the App Framework）。框架就像是应用的过程管理者（The framework is like a process manager for apps）——它管理应用的生命周期（开始、终止和聚焦）（it manages the app lifecycle (start, stop, focus)）。
Optional step: Add the Magnolia CMS
bin directory to the
PATH variable, for example
C:\Program Files\magnolia\apache-tomcat-5.5.27\bin. Setting the
PATH allows you to issue the Magnolia CMS
stop commands from anywhere without navigating to the installation directory first. Separate the path from existing paths with a semicolon ( ; ). If you do this, you also need to add
CATALINA_HOME to environment variables. Set the value of
CATALINA_HOME to the Tomcat installation directory, for example
可选步骤（Optional step）：为了您能够方便启动Magnolia CMS的
stop命令（无需进入到安装目录下）（To issue the Magnolia CMS start and stop commands from anywhere without navigating to the installation directory first），您可以在
C:\Program Files\magnolia\apache-tomcat-5.5.27\bin（you can add the Magnolia CMS bin directory to the PATH variable, for example C:\Program Files\magnolia\apache-tomcat-5.5.27\bin），使用英文分号（;）将该路径与已有路径分隔开（separate the path from existing paths with a semicolon ( ; )）。同时，您也需要在环境变量中添加
CATALINA_HOME（Meanwhile, you also need to add CATALINA_HOME to environment variables），并将它的值设置为Tomcat安装目录，如
C:\Program Files\magnolia\apache-tomcat-5.5.27（and set the value of CATALINA_HOME to the Tomcat installation directory, for example C:\Program Files\magnolia\apache-tomcat-5.5.27）
Passive voice vs. active voice
Passive voice is used less frequently in Chinese than in English. When passive voice appears a lot in Chinese, it may indicate the lack of localization. There are two ways to avoid this:
- Change passive voice to active by writing out the subject.
If no value is specified, the default value is used.
如不指定值，系统将使用默认值。(If no value is specified, the system will use the default value.)
- Reduce the times that the character "被" appears, because it's a sign of passive voice. In many cases, this character can be omitted without changing the meaning of a sentence. Alternatives such as "在" and "于" can also be used.
The page name is used in the URL.