[Koha-devel] Fwd: Streamlining frontend development in Koha

[Jesse]

I've been working on Rancor, a professional MARC editor for Koha
sponsored by ByWater and DGI, for the past year or so. As Rancor has a
lot more client-side complexity than many other parts of the staff
interface, I've run into some major frustrations. I have a proposed
solution for them, and would like feedback from both developers and
translators:

Let's rewrite Koha in GWT!

But seriously. The issues come down to translation. Making cleanly
translatable JavaScript frontend code using Koha's current system
requires a lot of finagling and ugly syntax, especially for any
complicated string. There are two problems.

Problem One:

For example, displaying "You have checked out X books, Y of which are
on hold" is frustrating to impossible for either the developer or
translator:

_("You have checked out ") + X + _(" books, ") + Y + _(" of which are on hold")

is easy for a developer to write, but gives the poor translator three
separate strings to translate. The commonly given solution is to
rewrite this as:

_("Books checked out: ") + X + _("Books on hold") + Y

which works, but is a bit less elegant, and not always realistic. An
informal best practice that has some precedent in the OPAC and
Datatables is to use named placeholders in the string:

_("You have checked out __X__ books, __Y__ of which are on
hold").replace("__X__", X).replace("__Y__", Y)

This is good, but currently has to be rewritten for every translated
string. I'd like to propose a syntax like the following:

_$("You have checked out $1 books, $2 of which are on hold", X, Y)

or

_$("You have checked out $X books, $Y of which are on hold", {X: X, Y: Y})

with a slight preference for the former. Either approach allows
translators to reorder substitutions as needed. The exact details of
the syntax are up for debate, but something that can be implemented
once, thrown into staff-global.js, and used everywhere is the goal.

Either approach would be treated the same as:

_("You have checked out $1 books, $2 of which are on hold")

for the purposes of generating .po's and creating translated templates
from existing .po's.

Problem two:

Currently, for JavaScript code to contain translated strings, it must
be placed within a .tt or .inc. This is a historic limitation of the
translation scripts
(http://bugs.koha-community.org/bugzilla3/show_bug.cgi?id=4503). The
stated reasons for not fixing it, besides the hairiness of the
translation scripts, are that a) most JavaScript code has been moved
to non-language specific directories and b) there are property-based
translation systems available for JavaScript (see the
datatables-strings.inc file for an example of how the latter works).

Here are my reasons for disagreeing with these two points:

a) Keeping most JavaScript code non-language-specific is a very
laudable goal, both in terms of separation of concerns and
deduplication of files in multi-language installs. I believe that the
translation system should allow for translation of strings in .js
files, however. Despite factoring out many modules and pieces of UI
infrastructure using Require.JS, Rancor is currently sitting at ~1200
lines of code that deal with showing error/informational messages to
the user, all of which has to be in a .tt or .inc in the current
system. This is untenable for any complex JS code.

b) While this is more of a matter of taste, I do not like the
properties-based translation system. For one thing, it punts the above
problem to a solution like is used for datatables, with the
translation strings in a .inc containing a single <script> and the
rest of the code in a .js. Also, it introduces a layer of indirection
that makes figuring out what is actually displayed to the user (and
tracing where a given message came from) needlessly complicated.

I believe that while the QA process should continue to encourage
splitting out as much functionality as possible into
non-language-specific JavaScript, _requiring_ it causes problems. I
propose that the translation scripts be extended to process _() (and
possibly _$()) directives in .js files in language-specific .../js/
directories.

(Note: this is not a "I think this is a fantastic idea that someone
else should work on" proposal. I am willing and in fact eager to make
these changes. But it would affect many people, so I want your
thoughts first.)

--
Jesse Weaver