[jbosstools-dev] Re: JBoss Tools .pot files checked in; careful when renaming .properties!

[Sean Flanigan]

Max Rydahl Andersen wrote:
> ok, I don't fully understand why it is better to use a different  
> "compressed" path than what
> is used in the src plugin - but if that is what the translators find best  
> then ok.

I'm not sure, but it's probably to do with the fact that dealing with
Java-style deep subdirectories is very difficult unless you're using a
Java IDE.  Particularly if you use the command-line.  And Gettext tools
are all command-line-based.

BTW, if you are saying there is another, existing, compressed path I
could have used, then I can't think what it is. Unless you mean
something like
hibernatetools-plugins-org.hibernate.eclipse.console-src-org.hibernate.eclipse.console.HibernateConsoleMessages.properties.

That would work, but I realised that keeping some of the path-segments
like "plugins" and "src" wasn't helping much, but made the compressed
paths ugly, and fragile in case of refactoring.

It's very much a compromise, because the translators would prefer to
have a single pot file per "project".  Most "projects" are probably
about the size of a JBT module, if not bigger, often an entire
application.  The gettext tools aren't great at dealing with lots of
small po/pot files (eg to share similar strings/translations appearing
in multiple pots).  One day I might work out a two-way mapping which
would allow multiple properties <-> single pot, but I don't know of any
existing standardised mapping, so I don't want to rush into it.

> Is the build capable of failing if a resource gets  moved/renamed and you  
> can't find a match ?
>
> /max

No, the build won't fail, but when the pot/po files are next merged
there should be a lot of orphaned messages found in the POs (and marked
as such).  Naturally, any missing messages will be replaced by the
original English at runtime, until fixed.

I'm not sure how/if the i18n build will be integrated with the normal
build, but it should be possible to write a junit test which tests all
locales for a complete set of translations, and fails if any are missing.

If I understand correctly, by default, Hudson would mark such a build as
"unstable" but carry on anyway.  We wouldn't want that behaviour all the
time (since complete translations won't be available), but it could be
made configurable.

>> G'day all,
>>
>> I finally bit the bullet and put in a somewhat kludgy workaround for the
>> fact that properties files are not kept in the same directory under each
>> plugin, but all over the place (src, src/main, resources, jbosscore,
>> ...).  I can always take out the workaround when
>> https://jira.jboss.org/jira/browse/JBIDE-2972 is resolved.
>>
>> With the workaround, the pot filenames should be fairly stable, so I've
>> checked in the converted pot files under i18n/po.
>>
>> I really, really tried to avoid checking in generated files like pot
>> files.  However, keeping pot files in the source tree seems to be a
>> universal convention for gettext projects, and corresponding pot and po
>> files are usually kept in the repository together.  This enables
>> (non-programmer) translators to merge new strings for translation just
>> by checking out the po directory, without having to run xgettext (or
>> Ant-Gettext, in this case) against the entire codebase themselves.
>>
>> Based on feedback from the L10n team, I have also changed the filename
>> mapping used when converting from .properties to .pot files.  The pot
>> filename now eliminates segments like "src", "src/main", "resources",
>> "jbosscore", etc which are very likely to change over time.  I have also
>> flattened the remaining directory hierarchy.
>>
>> I think this retais enough of the original path to prevent name
>> collisions, but shortens it enough to be more changeproof and easier for
>> translators to work with.
>>
>> With the new mapping, the names of source directories can be refactored
>> without affecting the .pots and thus invalidating translations.  For
>> instance, changing myplugin/src/**/*.properties to
>> myplugin/resources/**/*.properties is perfectly safe.   But changing the
>> name of a module, a plugin or a .properties file (or its package) will!
>>  (See the end of this email.)
>>
>> Thus the property file org/hibernate/console/ConsoleMessages.properties
>> in the plugin org.hibernate.eclipse (module hibernatetools) is mapped to:
>>
>> i18n/po/hibernatetools/org.hibernate.eclipse-org.hibernate.console.ConsoleMessages/
>> org.hibernate.console.ConsoleMessages.pot
>>
>> The po/pot files are still grouped into modules (for managability), and
>> we keep track of the plugin id and the resource path (ie the path used
>> at runtime to load the resource).  The resource path is used again for
>> the filename within the directory, partly to make it easier to find (eg
>> in Eclipse, press Ctrl-Shift-R, the enter *ConsoleMessages or other
>> wildcard).
>>
>> In accordance with the Gettext tools' default conventions, po files will
>> be kept in the same directory, but named ${locale}.po.  So the above
>> directory will look like this when translated:
>> i18n/po/hibernatetools/org.hibernate.eclipse-org.hibernate.console.ConsoleMessages/
>>   de_DE.po
>>   es_ES.po
>>   fr_FR.po
>>   org.hibernate.console.ConsoleMessages.pot
>>   pt_BR.po
>>   zh_CN.po
>>
>> Please be careful:
>> 1. when renaming modules, plugins, .properties files, or packages which
>> contain .properties files, or
>> 2. when moving plugins to a different module.
>>
>> Any of these changes will prevent existing translations (when we have
>> some) from being picked up, unless the affected po directories and files
>> are manually renamed to suit.  By me, probably.  But feel free to rename
>> the affected po directories/files if you feel confident to!
>>
>> I'm certainly not saying "don't rename things", but please try to go
>> easy on me!  Thanks!
>>
>> Regards,
>>
>> Sean.
-- 
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/20081202/b4d57cac/attachment.bin