Page tree
Skip to end of metadata
Go to start of metadata

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 stkArticle template.
激活后,在HTML的body元素里,body id="article" class="col-subcol-subcol"bodyID元素包含了article属性(attribute),并使用stkArticle模板里分配的bodyID属性(property)。

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

These terms include HTML, URL, Java, JavaScript, Servlet, and so on. For HTML and URL, they are easier to identify in acronym form. They don't have to be spelled out. For the other terms, their owners don't translate them and the users are used to the English words.

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.

Phrase order

Adverbial clauses starting with "to/in…" are usually placed before the action in a sentence in Chinese.

Create a products content node. This adds a new tile in the app launcher.

Attributive clauses

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 thePATH allows you to issue the Magnolia CMS start and 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 C:\Program Files\magnolia\apache-tomcat-5.5.27.


可选步骤(Optional step):为了您能够方便启动Magnolia CMS的startstop命令(无需进入到安装目录下)(To issue the Magnolia CMS start and stop commands from anywhere without navigating to the installation directory first),您可以在PATH变量里添加Magnolia CMS的bin目录,如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.


Antti's blog:

  • No labels