JBossToolsCodingGuidelines

Version 2

    NB: This document is a *draft*!

    General guidelines

    TBD

    Internationalisation aspects

    1. If possible, avoid static text in imagesIf 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.)

     


    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.)

     

    NB: This document is a *draft*!