Translator plugin : Help files translation patch

[evan]

Hello PKP World!

The Aristotle University of Thessaloniki, has been testing ocs for the last year, and it wasn't until recently when the need for localized help files came up. Albeit the Translator plugin is a great one, it does not offer the utilities for translating the help files. Therefore, you can have a conference in any locale you want, but the help is still in the master locale, which is english.

The Library and Information Centre of the University, where I work, supports and maintains all the web systems and thus I had to deal with the localization issue. The result was the patch I describe below.

About the patch.

The main goal this code serves, is to retrieve all the help files from ocsroot/help/xx_YY folder, and have them presented in an ascending order to the administrator, ready to be translated. The second major objective was to leave the original plugin files as intact as possible, so as to not interfere with any updates that will probably be applied in the future. Thus the files that have been changed a bit are TranslatorHandler.inc.php and locale.tpl.

The modifications needed for the former to work, have been limited to just three places: the import/require_once statements, the class that is extended, and a call to the parent edit() inside the edit function.

As far as the latter is concerned, I included a section which is responsible for displaying all the xml help files, that reveives.

The rest of the files are new and are as follows:

- Directory plugins/generic/translator:

CustomHandler.inc.php
helpTocFile.tpl
helpTopicFile.tpl

- Directory lib/pkp/classes/file:

EditableHelpFile.inc.php

-Directory lib/pkp/classes/i18n:

HelpFile.inc.php

-README.txt

In the README file you will find an installation guide.

All these files have been developed according to the original one's, and follow the same guidelines. The patch has been tested in ocs v2.3.5 and v2.3.4. The major difference between these two versions, is the class Locale that checks for a locale's validity. Ocs v2.3.4 uses the class Locale, while in the newer v2.3.5 it is AppLocale. I have included a check to overcome this issue.

In order for the code to work, you have to have installed your locale and a folder xx_YY with your help files (xx_YY is a locale's initials).

Any feedback, suggestions, corrections & additions are greatly appreciated.

Regards
Evan Savvidis

[asmecher]

Hi Evan,

Thanks, that sounds very useful! I've filed a bug at http://pkp.sfu.ca/bugzilla/show_bug.cgi?id=7562 to have a look at it and see if we can merge it into the core codebase for the next (2.4.0) release.

Regards,
Alec Smecher
Public Knowledge Project Team

[evan]

Hi Alec,

I'm glad the patch may be useful, thanks.

Regards,
Evan Savvidis

[evan]

Hello all,

this attachment is an updated version of the patch, that fixes a couple of things Ι had missed.

Specificaly in conference/toc/000002.xml file there is the following line

Code: Select all

<topic id="conference/topic/000020" title="Stats &amp; Reports" />

the code that saves the changes was choking on '&', and thus interrupting the whole saving process, leaving a broken xml help file.
I added the function sanitize in CustomHandler.inc.php, that checks for characters like this, and handles them appropriately.

Secondly i hadn't taken proper care of multiple section tags, so the relative template file (helpTopicFile.tpl), was only displaying the first section tag for translation (e.g. in conference\topic\000017.xml, only the first tag was visible). I modified CustomHandler.inc.php, helpTopicFile.tpl and EditableHelpFile.inc.php to fix this bug.

Finally i would like to thank Alexandros Gougousis (works at Technological Educational Institution of Crete), who first pointed out these 'inconveniences'

Best Regards
Evan Savvidis

[asmecher]

Hi Evan,

Just a heads-up -- the OJS 2.4.x line is the last family of releases that will include the current help files. We'll be moving to a more inline style of help, along with better external documentation. Just wanted to give you a warning before you spend too much time developing this further. I'll send one of our team members to this thread to describe the new approach a little more thoroughly.

Regards,
Alec Smecher
Public Knowledge Project Team

[jmacgreg]

Hi Evan,

As Alec mentioned, we are in fact reconfiguring how help is stored and managed in OCS (and our other applications). In a nutshell, we are retiring the old, isolated XML help files in favour of including help inline in the application itself (and stored in the regular XML locale files found in locale/en_US, locale/el_GR, etc.). This will make future translation easier, as all help documentation will be available to the translator plugin by default.

Unfortunately, there is no easy way to migrate the old help files into the new configuration, as the structure is quite different. (You can see an example of what the new help will look like in OMP, for example in this screenshot -- all of the smaller grey text is the new "inline" help.) The good news is that OCS 2.4.x, and your current contributions, will be supported for some time to come. If you have any questions, please just let us know!

Cheers,
James

[evan]

Hello guys,

thank you for letting me in on the situation. Indeed the new system looks more elegant.
One question though. Do you need me to send you the translated help files to incorporate them into the new system, or will it be easier for out team to translate it from scratch?

Regards,
Evan