[jbosstools-dev] Suggested coding guidelines for internationalisation

[John Graham]

If you add a plugin.properties to an existing plug-in project, be sure
that the following line is set in the plug-in's manifest.mf:

Bundle-Localization: plugin

or else it will not pick up the externalized values in
plugin.properties.

-- John

On Thu, 2008-10-23 at 17:26 +0200, Snjezana Peco wrote:
> There is a specific kind of properties files in Eclipse that are used 
> for internationalizing plugins and features, i.e., plugin.xml, 
> feature.xml and MANIFEST.MF. They are usually named plugin.properties 
> and feature.properties and placed in the root of a plugin/feature (out 
> of the source directory).
> 
> Snjeza
> 
> Sean Flanigan wrote:
> > 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.
> >
> >
> >   
> > ------------------------------------------------------------------------
> >
> > _______________________________________________
> > jbosstools-dev mailing list
> > jbosstools-dev at lists.jboss.org
> > https://lists.jboss.org/mailman/listinfo/jbosstools-dev
>