Transifex and anaconda Development
09-Mar-2011
by: David Cantrell <dcantrell@redhat.com>
-----------------------------------------------------------------------------

Setting up the new transifex-client on your system for anaconda builds.

1) Install the transifex-client package:
       yum install transifex-client
   -or-
       yum --enablerepo=updates-testing install transifex-client
   -or-
       yum --enablerepo=epel-testing install transifex-client

2) Create a Transifex.net account at https://fedora.transifex.net/
   NOTE:  This system is not linked to FAS, it's hosted by another company,
   so it requires another account at this time.  I'm sure this will change
   in the future, but this is how it is for now.

3) Configure 'tx' on your system:
       tx init
   Accept default host, fill in your username and password generated in #2.

Now tx is set up on your system.  The translation files will only be pulled
when a 'make release' is done.  The 'make dist' step will just create a tar
file of the what we have in our repo.  The 'make bumpver' step will also
push a new anaconda.pot file to Transifex, so any string changes are pushed
to them on a regular basis.

NOTE:  tx pull is slow.  This is why I only added it to the 'make bumpver'
step.

There are some other procedures related to tx that will have to be done
when we create new branches or when there are translation errors.


MAKING A RELEASE
----------------

git clean -d -x -f
./autogen.sh && ./configure --disable-static \
--enable-introspection --enable-gtk-doc
make bumpver                      # tx pull by dependent po-pull target
git commit -a -m "New version."   # DO NOT run 'git clean -d -x -f' after
make && make release              # signed tag happens after dist now

The process here is mostly the same.  I do not recommend that you run
git clean between 'make bumpver' and 'make release'.  The reason is you
will have to run 'tx pull' again and that's slow, plus translations may
have changed between the two steps.

The 'make tag' step now runs after 'make dist' in case dist generation
fails.  That way you don't end up with a partially created dist AND a
bad tag you have to delete.

The 'make scratch' target will also run po-pull to get translations.  If
we need translation files in other targets, we can add po-pull as a
dependent target.


DEALING WITH ERRORS IN *.po FILES
---------------------------------

Translators sometimes introduce errors in the .po files.  What we generally
do is try to fix it if it's an obvious typo, or just revert the change and
go back to the old po file.  Reverting is harder now since we are not
storing po files in our repo, but in severe cases we can go and fetch the
last build and pull the affected po file from there and use it to revert the
changes.

Here's an example of a po file error that will halt a 'make release':

    rm -f af.gmo && /usr/bin/msgfmt -c --statistics -o af.gmo af.po
    af.po:7: field `Language-Team' still has initial default value
    af.po:1614: number of format specifications in 'msgid' and 'msgstr[1]' does not match
    /usr/bin/msgfmt: found 1 fatal error

In this case, I am going to the last known good af.po.  To update Transifex,
I do:

    cp /path/to/last/known/good/af.po po/af.po
    touch po/af.po
    tx push -t -l af

The touch is necessary because transifex.net uses timestamps to determine
if it should update its translation data with the po file you are asking
it to use.


CREATING A NEW ANACONDA BRANCH
------------------------------

When we make a new branch, we need to branch the translation files.

First you need to populate the project with the initial po files. I suggest
using the ones from the master branch, e.g.:

    git checkout master
    git clean -xdf
    tx pull -a
    # leave the *.po files in the po/ subdirectory
    git checkout BRANCH_NAME

Next you need to update the transifex config with the new branch:

    tx set --execute --auto-local -r anaconda.BRANCH_NAME -s en -t PO \
           -f po/anaconda.pot "po/<lang>.po"

The last argument is correct as-is, it's not a place where you substitute
something for <lang>.  The BRANCH_NAME will be something other than 'master'.
For example, when we branch for F-20:

    tx set --execute --auto-local -r anaconda.f20-branch -s en -t PO \
           -f po/anaconda.pot "po/<lang>.po"

Check the .tx/config file on the branch to ensure it references the correct
anaconda.BRANCH_NAME in Transifex and remove the [anaconda.master] block so
that it doesn't try to push to master and the new branch.

Now you can run:

    tx push -s -t

This will push the po files and anaconda.pot from master to the BRANCH_NAME
resource for anaconda in Transifex.  This is just an initial seed that the
translation team can work with.  And since we branch from master, the code
should be more or less in sync with the po files at branch time.

Don't forget to commit the new .tx/config file to the branch.
