[jsword-devel] BibleDesktop/JSword translations

[DM Smith]

I have made a few changes regarding the "action" property files as it  
impacts doing translations of the application into other languages.

The action property files are the ones that describe a Name, Small and  
Large Icons, Short and Long descriptions, Initial Enable state,  
Mnemonics and Accelerators.

There are several problems in doing translations. Here are the ones I  
addressed and how I addressed them.
1) There are some entries which should not be internationalized  
(i18n). This means that they either need to be repeated verbatim in  
each translation or deleted. The problem with repeating them is that  
they are hard to keep in synchronization across the set of  
translations, should there need to be a change. Also, it is confusing  
to have values that don't need to be translated.

The JInto plugin that many of us are using to create and maintain the  
translated files requires that the values be repeated. This has caused  
some errors such as buttons and menu items being disabled and icons  
not showing up.

Regarding this, I have split the action file into two parts. One part  
is a control file and the other is a text file. Only the text file  
needs to be translated. For example, we had Desktop.properties and now  
we have added Desktop_control.properties.

The entries in Desktop.properties that have been moved to  
Desktop_control.properties are like the following:
Xxx.Enabled
Xxx.SmallIcon
Xxx.LargeIcon

If there is a need to supply alternate icons, we can do "translations"  
of these files. But it should not be necessary. (We are looking to  
replace the "Book" icons and the ~1 and ~5 icons with ones that don't  
need to be i18ned)

2) Another problem was that there were some unnecessary entries in  
these "action" property files. These are entries in the default file  
that had nothing to the right of the = sign. I think that these made  
translations difficult as it was not clear why they were there. It  
would be far better for every line in a translated file to need to be  
translated.

Another kind of unnecessary entry is one that matches the default. For  
example, Xxx.Enabled=true is pretty much the same as not having the  
entry. For this reason, I deleted them everywhere. (Of course  
Yyy.Enabled=false, was left)

As a solution to this problem, I deleted across all the property files  
any entries that were unnecessary.

3) The field Xxx.Mnemonic=L is problematic. A mnemonic is a letter  
that is underlined. In this case, the first letter 'L' (regardless of  
case) would be underlined in the Xxx.Name field. Nearly every last  
mnemonic in a translation did not match a letter in the name. This is  
a common convention on Windows and many find it useful on menus for  
keyboard navigation. It is also typical on Linux. On Mac, it is  
suppressed as the Mac UI guidelines say they are not to be used.

I deleted every value that did not match and there was no obvious  
value that should be used. That is I left the key followed by an =  
sign and no value to the right. If there was an obvious value, I fixed  
the entry.

Some problems that I have not addressed:
1) There are some strings that are repeated in many actions across  
many files, such as Yes, No, OK, Cancel, Help, .... These should only  
need to be specified once. I will be adding an "alias" mechanism to  
address these. I may get to this later today. An alias will have look  
just like a regular action definition.

The basic idea is as follows:
In o.c.c.util there will be Alias.properties and all its translations.  
This will be used by ActionFactory to do substitutions.

In a property file such as Desktop.properties one would invoke an  
alias with:
Xxx.Name=Alias.OK

For Xxx, any entries in Alias.properties for OK.field=value that are  
appropriate, they can be deleted. If one wishes to override any values  
from the Alias file, they would be retained in Xxx definition.

2) Actions are shared, which is generally a good thing. This means  
that the same action can be on a menu, in the tool bar and in a right- 
click context popup menu without repeating code. But it can also be a  
bad thing in that it forces the proliferation of some actions just so  
that they can avoid sharing. I think the solution to this is to have  
Xxx.Shared=false for actions that can be reused but are not shared.


3) It is hard to know in the Msg.property files what is important to  
translate and which is unimportant. These should be split into  
different Msg files. Until I get around to this, follow the lead of  
the Farsi translation.

4) Finding the properties files to translate is not straightforward or  
obvious. It would be nice to come up with a way to make it easier.

One suggestion would be to co-locate the files in a single folder in  
each of common, common-swing, jsword and bibledesktop. An advantage of  
co-locating them would be that it would be easier to package  
BibleDesktop for just one language. The properties would be in their  
own jars on a per language basis. One would add language packs as they  
found fit. (But unless someone is up for it, that is a ways off)

For those of you doing translations, I'd love to have feedback and  
suggestions.

Working together for His Kingdom,
	DM