Guides for message definition - quality-manager/onboarding GitHub Wiki

PII (Program Integrated Information) is basically user-visible text in the application. In order to translate into other languages, we need to be careful defining the messages.

Do not use strings concatenation

Remember you must. The order of the words that make up a sentence is generally not always the same from one language to another.

Singular or plural

Do not use "(s)" which may not mean anything in some languages. For example, instead of a message "Delete %1 execution record(s)", just use the plural form "Delete %1 execution records". Or even better, define two messages "Delete 1 execution record" and "Delete %1 execution records" and have the code check for singular or plural and use the corresponding message.

Comment always helps

This is more like a puzzle than a message definition. What can those variables be? "Out of %2 %1, %3 %1 copied. Remaining %4 %1 already exist for the target iteration."

Add comment next to the string documenting where the message is used and the values that will be substituted into the variables.

Avoid using variables that may not be translatable

Some languages translate the article or adjective depends on the gender of the following noun. "The owner of the delivered snapshot "{0}" has been changed to the {1} "{2}." - can't translate "the" without knowing what is {1}. "Create linked {0} in project area {1}" - can't translate "linked" without knowing the gender of {0} and not all values of {0} are the same gender. Created separated messages instead.

"Create linked defect in project area ${1}" "Create linked enhancement in project area ${1}" "Create linked test plan in project area ${1}" "Create linked test case in project area ${1}"

Do not reuse labels in different context

For English, a tool-tip or label of a button, such as "Add Requirement Collection" is the same as the title of the dialog that the action brings up. Other languages might translate the same label differently as a verb form for button label vs a noun form for dialog title. We need to have two different message definitions for the same English string for different context.

Prevent CHKPII error and warning

CHKPII is a PII validation tool that ran during a build that gather all the PII into zip files for the translation drop. If there is any CHKPII error or warning in a message file, the PII of the entire component of the message file will be skipped from the zip. There are a few common errors:

Duplicated message key - very likely copy and paste mistake. Can be avoided when adding new message by just do a Control-F to search the message key for duplicate in the editor. Missing NLS_MESSAGEFORMAT - .properties message files need to have declaration of NLS_MESSAGEFORMAT_VAR or NLS_MESSAGEFORMAT_NONE to process or skip single quote for Java MessageFomat. Something likely forgot when creating a new message file. Single quote found in NLS_MESSAGEFORMAT_VAR message file - single quote is processed and it is not expect to have single quote (escaped character) in message files for translation. Use two single quotes in the message definition for a single quote in the display. Or just use double quote.