[jboss-user] [JBoss Tools] Document updated/added: "JBossToolsCodingGuidelines"

[Max Andersen]

User development,

The document "JBossToolsCodingGuidelines", was updated Jan 20, 2010
by Max Andersen.

To view the document, visit:
http://community.jboss.org/docs/DOC-12852#cf

Document:
--------------------------------------------------------------
h1. NB: This document is a *draft*!
* 
#NB_This_document_is_a_draft


** 
#General_guidelines


** 
#Internationalisation_aspects


* 
#NB_This_document_is_a_draft_379786



h2. General guidelines
TBD



h2. Internationalisation aspects
1. *If possible, avoid static text in images*.  If you need text in an image, it's best to draw it on top at runtime.  That way, we can pull in translated text.
 
 


2. *Mark NON-TRANSLATABLE strings in .properties files.*  If some of the strings in a .properties file aren't meant to be translated (eg an HTML template, the text of a license agreement, or a configuration item to hold a port number), adding NON-TRANSLATABLE comments will ensure that the string/strings aren't sent off for translation.
 
For example:
# START NON-TRANSLATABLE
def_sc_js_html_content=<script type\="text/javascript">\n\t\n</script>
# END NON-TRANSLATABLE
 

If you have a whole block of non-translatable properties (or an entire file), you can just put # START NON-TRANSLATABLE before the first, and # END NON-TRANSLATABLE after the last.  (And yes, you can nest NON-TRANSLATABLE blocks if you really want to.)
 
http://wiki.eclipse.org/Eclipse_Globalization_Guidelines#Non-translatable_Message_Strings



3. *Delete messages which become obsolete.*  When removing code which has (or might contain) externalised strings, please check whether you can delete the strings from the relevant properties files.  This will save translators from translating text which will never be used!


 
4. *Avoid concatenating externalised strings.*  For instance:
messages.properties:
  InvalidFilename1=The filename '
  InvalidFilename2=' is not valid.
MyClass.java:
  setMessage(Messages.InvalidFilename1 + filename +
    Messages.InvalidFilename2);
 
I'm not a translator, but I understand it's not possible to translate two half-sentences, jam them together with a variable in between, and have the result mean anything useful in most languages.  Unless the two languages have the same word-order (eg English -> Pig Latin) the *sentence will break*.
 

Instead, use a single string, passed though MessageFormat like this:
messages.properties:
  InvalidFilename=The filename ''{0}'' is not valid.
MyClass.java:
  setMessage(MessageFormat.format(Messages.InvalidFilename, fileName));
 
(Note that MessageFormat requires single quotes (apostrophes) to be repeated.)
 
h1. NB: This document is a *draft*!



--------------------------------------------------------------