View source for I18n sanity

== The problem ==

We use logical keys for our translations for historical reasons (years
ago when our tools were written in TCL that's how you did it, and Zope
allows for the option).

Logical keys aren't bad on their own... the problem is that in general
the rest of the world doesn't seem to use them.  Thusly we've had to
write our own tools to move our translation files around, sync things,
etc; these tools require a lot of specialized knowledge to maintain
and tend to be fairly fragile.  It would be significantly easier
on ourselves if we could just move away from them.

To do that, we need to move from logical to english keys.  Given the
complexity of our existing system this won't be easy... one attempt at
moving was made before and was later given up on.  Here's to success
on the second try!  A relevant plan is laid out below.

== The plan! ==

The general plan is that we'll have a script that can go and extract
everything automatically from our sets of tools that use cc.i18n.

=== Switch back cc.i18n to Babel and just wrap writing in polib ===

I've half fixed some recent issues we've found with the polib, but not
completely.  It might not be worth finishing fixing these if we're
going to tear this all down anyway.  It might be worth just switching
things back to Babel and wrapping the writing calls in polib to handle
the formatting pains we were having with Transifex and git without
having to worry about things working properly otherwise.

=== Moving cc.engine templates to Jinja2... why? ===

Why Jinja2?  Why move templating systems at all?

Actually I like Zope Page Templates, and it's actually possible to not
use logical keys with them.  However certain types of translations
require *manually editing* the extracted strings (basically ones with
special xml attributes), which simply won't work in a glorious future
of automatic-extraction.

Jinja2 seems to be the most popular templating system right now and is
almost exactly like Django's templating system with a few
improvements.  (You can pass in arguments to functions!  Etc.)  There
are a few other templating systems perhaps worthy of consideration
(Mako, etc) but they don't look like they have anything better to
offer, particularly in the area of translation stuff.

=== The <nowiki>{{ cctrans() }}</nowiki> intermediary step ===

Jinja has a kind of translation system we can use with {% trans %}
tags, but jumping straight into jinja with {% trans %} tags probably
won't work because of several things that end up in a kind of
chicken-egg problem:

* Jinja2's variables-in-translations setup is different, using %(foo)s variable style rather than ${foo} style we currently use
* Moving templates from one system to another is non-trivial.  We're going to need to make sure our templates actually *work* at the same time that we're trying to migrate to the same format.  That's not easy to do both.

To fix this, we should use an interim <nowiki>cctrans()</nowiki> function inside the templates, kind of like:

<code>
  <nowiki>{{ cctrans("logical_key_name", var=foo.bar(), blah=baz) }}</nowiki>
</code>

Later on these can be auto-translated into *real* trans tags like:

<code>
  {% trans var=foo.bar(), blah=baz %}
    text content of trans goes here!  Figured out by reading from the
    logical keys.
  {% endtrans %}
</code>

=== Metamorphosis tools ===

./gregor.py ? :)

==== template metamorphosis ====

We need to move our templates from <nowiki>{{ cctrans() }}->{% trans %},</nowiki> as
described above.  The tools should be smart enough to make the ${foo}
to %(foo)s transformation as described below also.

==== ${foo} to %(foo)s metamorphosis ====

We'll also need to convert all ${foo} to %(foo)s in the .po files and
alert translators that this is the new format.  (Also, will
translators be okay with this confusing "s" after %(foo) in %(foo)s?
Will that confuse them?)

=== Move our other programs over. ===

Probably cc.license, cc.api, cc.i18n, cc.deedscraper scraper might all
need some (comparatively small) adjustments for this format.

=== Write script to auto-extract everything ===

Not only do we need to auto-extract things from all projects, we need
to combine them into one big file.  We should run a check to make sure
we aren't "missing" anything and if we are if it's still a string in
use.

=== Moving files and Transifex considerations? ===

We'll also be moving the structure of files around, so maybe we'll
need to change our layout?  Or maybe we won't, maybe we can keep the
old layout and just change our programs to expect the new one with the
po-style files in the same place.

Anyway, does this affect Transifex?  We'll need to think carefully
about this.