[jbosstools-dev] Suggested coding guidelines for internationalisation

To make the i18n build tools less ad-hoc and more reliable, it would help if I could make some assumptions about the structure of the source code. I'm in the process of preparing some jira issues for existing wrinkles to be ironed out, but there are a few things to keep in mind for future development. 1. Avoid including 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. Otherwise, we would have to provide multiple, localised, versions of the image, and that (a) wastes space, and (b) would mean a more complex build process. (In other words, we haven't yet worked out how to support it in the build!) 2. Avoid locale-specific .properties files in the source tree. All translations should be in .po files. There are at least three different categories of .properties files: a. .properties files used as the baseline for UI text (and for translators to translate), eg messages.properties b. .properties files which contain locale-specific text, eg messages_en.properties, messages_fr.properties c. .properties files used as configuration, eg hibernate.properties I need to extract category (a) so that it can be translated. (If translators change category (c) config, things might break.) There are a few en-specific .properties files in svn, but as they don't live under ${plugin}/src, they shouldn't cause a problem for now: ./seam/tests/org.jboss.tools.seam.core.test/projects/Test1/src/messages_en.properties ./seam/tests/org.jboss.tools.seam.ui.test/projects/TestSeamELContentAssist/src/model/messages_en.properties ./documentation/development/usecases/en/modules/projectexample/lamp/src/action/messages_en.properties So please avoid putting locale-specific .properties files in the main source tree, even for English (messages_en.properties). Locale-specific text should go into the .po files which will live under trunk/localization/{module}/plugins/{plugin}/resources/text/org/jboss/ The locale-specific .properties files will be generated as part of the build process, by "localization"'s build.xml, for use at runtime. Remember, edit the .po file, not the generated .properties file! 3. Avoid underscores in the basenames of .properties files. Underscores are used to separate the basename from the locale code, so these underscores could lead to problems. At present these files do contain translatable text: ./common/plugins/org.jboss.tools.common.model.ui/templates/web-facesconfig_1_2.properties ./common/plugins/org.jboss.tools.common.model.ui/templates/web-facesconfig_1_0.properties ./common/plugins/org.jboss.tools.common.model.ui/templates/web-facesconfig_1_1.properties I will be submitting a jira about these files, but we should try to avoid similar filenames in future. 4. Keep source code and properties files in separate, well-defined locations. In JBoss Tools, I have identified translatable .properties in the following directories under various ${plugin} dirs: src/main src jbosscore jbossui templates template-src From an i18n point of view, it doesn't really matter about the source directories (src, src/main, jbosscore...), as long as translatable resources can be found in one place. To avoid svn conflicts and make everyone's lives easier, I would probably leave the source dirs alone, but move all translatable properties files into, say, ${plugin}/resources/text. Suggestions welcome, though. Is there somewhere on the wiki this sort of thing should be recorded? Thanks Sean -- Sean Flanigan Senior Software Engineer Engineering - Internationalisation Red Hat