Localizing Derby Messages

Overview

This page describes how to write and maintain messages which are translated from English into other languages.

Translatability Guidelines

Here are some general guidelines for writing messages which are easy to translate. These are conventions expected by the team which translated Derby messages for the past several years. Most of these guidelines are common sense rules and should continue to be useful even if another team picks up the translation task later on. Note that most Derby messages are defined by xml descriptors in java/engine/org/apache/derby/loc/messages.xml. Further guidelines for that file can be found here.

Concatenation

Avoid writing code which concatenates two, independently localized message strings. The concatenation may make sense in English but come out as gibberish when translated into another language. If you must concatenate two strings, make sure that they are both complete sentences.

Arguments (Placeholders)

Derby messages are processed by the java.text.MessageFormat.format() method. That method plugs values into argument placeholders called {0}, {1}, etc.. When you define these arguments in messages.xml, give them meaningful names. When you define these arguments in other English properties files, consider adding comments which will help translators understand what kinds of values will be plugged into the messages. The following conventions will help the translators:

• Put a noun qualifier BEFORE each argument. This will tell the translator what kind of value is going to be plugged in. For instance, this is a good message: "No such column in table {0}." Avoid putting the qualifier AFTER the argument, e.g., "No such column in the {0} table."
• All arguments should be nouns. Other parts of speech create translation problems.
• Don't precede the argument with an article (a, the), an adjective, or a possessive (your). These create problems for highly inflected languages.
• Don't create arguments which can be both singular and plural.
• Never create a plural by appending "s" to an argument. For instance, don't write something like this: "No such {0}s in table."
• Don't use an apostrophe to turn an argument into a possessive. For instance, don't write something like this: "The table {0}'s columns have incompatible types.
• Avoid putting many arguments in a single message. More arguments make the message harder to understand and translate.
  

Untranslatable Terms

The translators will NOT translate the following kinds of terms. Terms which have these forms are assumed to be keywords or code fragments which don't need translation:

• ALL CAPS.
• camelCaseWords
• wordsthataregluedtogether
• words_containing_an_underscore$or$dollar$sign
  
  

Derby Message Files

Derby message files are encoded in ISO-8859-1. The reasons for this are explained in the 2010-01-04 comments on DERBY-4492.

The English message sources live in the following locations:

Localizations for other languages live in the same directories as the English versions. Supported languages include:

Translation Cadence

Typically, as the community develops a new feature release, more messages accumulate in the English message sources. Those English versions need to be localized. Those localizations, in turn, typically turn up in follow-on maintenance releases. Localizations are more up-to-date for some languages than for others.

Typically, localizations for several languages are provided by committers who work for large companies and who have access to their companies' translation teams. Although this translating work happens outside the Derby community, committers checkin this contribution by proxy, under section 4 of their ICLAs.

This process reflects the consensus of two discussions which took place on the legal-discuss mailing list:

• Blanket software grant
• Question about handling external updates to contributed files
  

and a discussion which took place on the derby-dev list.

The following post sums up the consensus:

"If you have permission from your company, you can contribute them under your own ICLA. However, it is better for your sake (not Apache's) that you have a signed CCLA in place that formally says you have permission to commit stuff that is copyright the company. Only one CCLA is needed for all such commits."

Testing Chinese Localizations on Windows 7

1. Setting up the system:
   
   • Make sure you have Chinese (Traditional, Taiwan) language pack installed on your Windows 7 machine. Go to Control Panel->Clock, Language, and Region->Install or uninstall display languages->Install display languages->Launch Windows Updates (This is some screen shop in turn of what you can download http://windows7center.com/news/windows-7-rtm-language-packs-now-available-via-windows-update/)
     

2. Change system locale to use Chinese (Traditional, Taiwan):

• Go to Control Panel->Clock, Language, and Region->Install or uninstall display languages->Administrative->Change System Locale->Choose Chinese (Traditional, Taiwan)
  

3. Setup ij to displaye Chinese (Traditional, Taiwan)

• Please use the following option for org.apach.derby.tools.ij: -Dderby.ui.locale=zh_TW –Dderby.ui.codeset=big5
  

4. Setup derby server (database side) to display Chinese (Traditional, Taiwan)

• -Duser.language=zh –Duser.country=TW
  

For example:

$ java -Duser.language=zh -Duser.country=TW org.apache.derby.tools.ij -p derby.

properties

ij 版本 10.7

ij> connect 'jdbc:derby:aa';

錯誤 XJ004：找不到資料庫 'aa'。

ij> connect 'jdbc:derby:test_chinese;create=true;user=REFRESH;password=Refresh';

ij> select * from 家長;

錯誤 42Y07：綱目 'REFRESH' 不存在。

ij> create table 中文(stroke int, 字 varchar(4));

已插入/更新/刪除 0 列

ij> insert into 中文 values (1, '國');

• 已插入/更新/刪除 1 列
  

ij> insert into 中文 values (2, '生', '09-17-2010');

• 錯誤 42802：指派的值數目與指定的或隱含的直欄數不相同
  

To test Chinese (Simplified, PRC) for Derby on Windows 7

1. Have Chinese (Simplified, PRC) installed.
   

(A detail instruction on install Chinese (Simplified, PRC) can be found in:

http://windows7center.com/tutorials/how-to-download-and-install-windows-7-beta-language-packs-mui-packs/

2. Change system locale to Chinese (Simplified, PRC)

3. Setup ij to display Chinese (Simplified, PRC)

• Please use the following option:
  
• -Dderby.ui.locale=zh_CN –Dderby.ui.codeset=GB2312 .

4. Setup derby server (database side) to display Chinese (Simplified, PRC)

• Please use the following option:
• -Duser.language=zh –Duser.country=CN
  

For example:

$ java -Duser.language=zh -Duser.country=CN org.apache.derby.tools.ij -p derby.

properties

ij ++版本 10.7

ij> connect 'jdbc:derby:test_cn;create=true;user=REFRESH;password=Refresh';

ij> values current_date;

1

2010-09-11

已选择 1 行

ij> select * from aa;

错误 42Y07：模式“REFRESH”不存在。

ij> create table 登录 (输入 int, 记录 varchar(4));

已插入／更新／删除 0 行

ij> insert into 登录 values (1, '北京');

已插入／更新／删除 1 行

ij> insert into 登录 values (1, '重庆', '广州');

错误 42802：已分配值的数目与指定列或暗指列的数目不同。

. One can also use java program to look at the messages_zh_CN.properties. Please use –Dfile.encoding=Cp939 for Chinese (Simplified, PRC ) and –Dfile.encoding=Cp950 for Chinese(Traditional, Taiwan)