[jbosstools-dev] Suggested coding guidelines for internationalisation

[Sean Flanigan]

Max Rydahl Andersen wrote:
>> 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 ?

Don't hold me to it, but I think that's generally true.

>> 2. Avoid locale-specific .properties files in the source tree.  All
>> <snip>
>> 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.

Okay.

>> 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 ?

If you're referring to files like
/org.jboss.ide.eclipse.as.ui/jbossui/org/jboss/tools/as/wst/server/ui/action/messages.properties,
correct and correct.

Just don't create either of these:
/org.jboss.ide.eclipse.as.ui/jbossui/org/jboss/tools/as/wst/server/ui/action/messages_en.properties
/org.jboss.ide.eclipse.as.ui/jbossui/org/jboss/tools/as/wst/server/ui/action/messages_fr.properties

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

Empty?  Oh, so they are.  Okay, it's coming back to me.
/org.jboss.tools.common.model.ui/templates/default-templates.properties
does contain English text, so I assumed I have to process that
directory, but those other files contain underscores, which means they
could cause problems.

There were a few other .properties files under org.jboss.*/templates/,
and I just noticed that the .xml files contained English text, but
perhaps we can ignore all of the templates/ directories, at least for now?

> 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 ?

True, I can't think of anything that it will break at the moment, I've
just got a bad feeling about this.  For instance, if one day we import
some messages_${locale}.properties to be converted to .po, suddenly the
"_"s will be significant.

But it's probably not worth worrying too much about.

<snip>
>> 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) ?

I don't think I'm suggesting what you think I am.

We just move ./src/org/jboss/tools/as/Messages.properties would be moved to
./resources/text/org/jboss/tools/as/Messages.properties,
add resources/text to the compilers' sourcepaths (Ant and Eclipse), and
the file ends up in exactly the same pathname in the compiled jar.  At
runtime, you still look up org/jboss/tools/as/Messages.properties.

Or from the class org.jboss.tools.as.Messages, you can use a
class-relative resource path of Messages.properties, same as always.  No
extra build step, just a minor change in build configuration.

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

Okay.


-- 
Sean Flanigan

Senior Software Engineer
Engineering - Internationalisation
Red Hat

-------------- next part --------------
A non-text attachment was scrubbed...
Name: signature.asc
Type: application/pgp-signature
Size: 551 bytes
Desc: OpenPGP digital signature
Url : http://lists.jboss.org/pipermail/jbosstools-dev/attachments/20081023/7fd78685/attachment.bin