[jbosstools-dev] Suggested coding guidelines for internationalisation

[Max Rydahl Andersen]

p.s. I see you are also creating jira issues for these; lets keep the  
discussion
on the jiras so things are together.

/max

>> 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!)
>
> Thinking on these I *think* the only things we have is the splashscreen  
> (which
> cannot be dynamically calculated so it needs a localized version and  
> eclipse
> supports that afaik)
>
> Otherwise it is just icons with acronyms, i.e. there is an icon with HQL  
> in the lower
> right - but I assume you would not translate HQL anyway since it's a  
> (technical) name and not a verb, correct ?
>
>> 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
>
> These are all from examples/test/doc projects and need to stay as is for  
> now.
> They don't end up in the enduser-distribution.
>
>> 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!
>
> For main dev, we would just edit the original source properties file,  
> correct ?
> Your tooling will use those as input to your .po translation, correct ?
>
>> 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.
>
> hmm - these are actually empty so i'm not sure what they are needed for.
> Again, these are templates used for generating other projects so not  
> sure it will be relevant
> to localize it.
>
> But is this not irrelevant since resourcebundles (and I assume pot too)  
> just take the bsae name
> (in this case e.g. web-facesconfig_1_2) and then append the localization  
> to find localized version.
>
> I agree it should be avoided to avoid confusion, but technically it  
> should just work find ?
>
>> 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.
>
> I would really really hate if the resources would have to move out of
> the src trees. That would require us to have an extra build step when
> just developing of copying the resources. The files would also still
> have to have the full qualified name to be looked up.
>
> i.e. src/org/jboss/tools/as/Messages.properties would end up being
> resource/org/jboss/tools/as/Messages.properties anyway. Wouldn't it
> be easier to just get the UI resource properties to have the same name,
> i.e. Messages.properties (and the sibling class Messages.java) ?
>
>> Is there somewhere on the wiki this sort of thing should be recorded?
>
> jboss.org/tools, click wiki and add them there (lets put a "This is a  
> *draft*" until
> we reach a conscensus)
>



-- 
/max