How to use GNOME cvs as a translator

[Christian Rose <menthos menthos com>]

Due to popular demand, here are some instructions for how to use GNOME
cvs for those who have recieved a GNOME cvs account. We should probably
put this info on a web page (help is wanted), but a mail will have to do
for now...


How to use GNOME cvs as a translator
====================================
As a frequent GNOME translator, you can apply for a cvs account. These
instructions are for those who have recieved an account but are unsure
about how to proceed and use it for adding and updating their
translations.

How to connect to the server should have been described with your
account approval, and is not explained in these instructions.
We will also use the language code "ll" as an example below. Replace it
with your own language code.

Important warning before we begin
---------------------------------
With a non-anonymous GNOME CVS account you have full access to the
master GNOME code repository, and with that comes responsibility. Don't
change *ANYTHING* in any module unless you are absolutely sure you are
allowed to do so. When in doubt, always ask the maintainers of the
module. Information about the maintainers of the module is usually in a
file called MAINTAINERS in the module, and there's sometimes also a file
called HACKING that contains useful information.

As a translator, you will mostly be dealing with the "po" directories of
the modules. You of course are allowed to add or update a ll.po without
asking for permission, but here are a couple of things you should
remember to do before any mn.po commit:

* Make sure the file is encoded in UTF-8 (for GNOME2/GTK2 software)
* Make sure the file passes the "msgfmt -cv ll.po" test
* Add an entry at the top of the "ChangeLog" file in the po directory.
Look at the other entries for how the format looks like. Remember to use
UTF-8 in ChangeLogs (that's the only way everyone can have their names
spelled correctly), and use double spaces and tabs at the correct
places. This is the usual format:

YYYY-MM-DD[space][space]Firstname[space]Lastname[space][space]<email@address>
[newline]
[tab]*[space]filename:[space]Comment
[newline]

Example:
2003-01-22  Christian Rose  <menthos@menthos.com>

	* sv.po: Updated Swedish translation.


When you add a ll.po to a module that didn't have one before, you also
need to do:

* Add "ll" to the list of language codes in the module's "configure.in"
file
* Add an appropriate entry to the "ChangeLog" file in the same
directory.

Also, whenever you commit, you will be asked to enter a commit comment.
Use the same format for that comment as with the ChangeLog ones (you can
often re-use your ChangeLog comment as commit comment).

Software requirements
---------------------
You should also make sure that you always have the latest intltool
release installed on your computer, so that you get all messages. The
current release is 0.25 as of this writing. New intltool releases are
also announced on gnome-i18n@gnome.org for your convenience.

How to checkout a module
------------------------
Retrieving a module is called "checking out" in cvs lingua. "co" below
is a shorter form of "checkout"; cvs allows for both of these namings.
How to checkout a module:

    cvs -z3 co modulename

Example: cvs -z3 co libgnome

The above example will check out the "HEAD" (default) branch of the
"libgnomeui" module to a "libgnome" directory on your computer. However,
sometimes a different branch should be used:

    cvs -z3 -r branchname modulename

Example: cvs -z3 co -r gnome-2-2 gconf

The above example will check out the "gnome-2-2" branch of the "gconf"
module to a "gconf" directory on your computer. However, sometimes it's
easier to have a branch in a directory with the branchname, so as to not
confuse it with HEAD:

    cvs -z3 -r branchname -d directoryname modulename

Example: cvs -z3 co -r gnome-2-2 -d gconf-gnome-2-2 gconf

The above example will check out the "gnome-2-2" branch of the "gconf"
module to a "gconf-gnome-2-2" directory on your computer.

How to update a module
----------------------
Once you have checked out a module and have it on your hard drive, you
usually don't need to check it out again to retrieve its latest state.
Instead you can simply update it, or "up" it as it's called in cvs
lingua, by entering the module directory and running the following:

    cvs -z3 up -Pd

Example: cd gconf; cvs -z3 up -Pd

As cvs updates each file, it displays some info. Below is a legend:
* U means the file has been Updated (usually a larger change or a
completely new file)
* P means Patch (a smaller change)
* "...is no longer pertinent..." means the file has been removed.

What was done?
--------------
If you want to know what has been done to a file, you can look at its
log. The log is the list of revisions of the file together with the
respective cvs commit comments:

    cvs -z3 log file

Example: cvs -z3 log src/foo.c | less

Each revision of a file has a number. You can use that to produce diffs:

    cvs -z3 diff -u -r revision file

Example: cvs -z3 diff -u -r 1.23 src/foo.c | less

The above example will list the changes done to the "src/foo.c" file,
since the "1.23" revision of said file, in "diff -u" format, one page at
the time (less).
If you just use "cvs -z3 diff -u file", you'll see all changes done to
your local copy of the file compared to the latest cvs revision.

How to add a new translation
----------------------------
Let's go through all the steps of adding a new "ll" translation in an
example. We'll use gconf "gnome-2-2" branch as the example:

# Checkout it since we didn't have it checked out already
cvs -z3 co -r gnome-2-2 -d gconf-gnome-2-2 gconf
# Go to the po directory
cd gconf-gnome-2-2/po
# Create the pot file
intltool-update --pot
# Rename the pot file to ll.po
mv GConf2.pot ll.po
# Editing the file, creating the translation! :)
vi ll.po
# Convert the file to UTF-8 (you can skip this if it's UTF-8 already)
mcgconv -t UTF-8 ll.po > ll.po.new && mv ll.po.new ll.po
# Check the file for errors (IMPORTANT! Don't forget this step)
msgconv -cv -o /dev/null ll.po
# Mark the file for addition
cvs add ll.po
# Create a ChangeLog entry
vi ChangeLog
# Go to the parent directory
cd ..
# Add "ll" to the ALL_LINGUAS line of configure.in
vi configure.in
# Create a ChangeLog entry
vi ChangeLog
# Commit everything (don't forget to add ChangeLog-style commit comment)
cvs commit
# Done!

How to update an existing translation
-------------------------------------
Let's go through all the steps of updating an existing "ll" translation
in an example. We'll use gconf "gnome-2-2" branch as the example:

# Go to the module dir (we happened to already have it checked out)
cd gconf-gnome-2-2
# Update everything in this module to match the latest state of cvs
cvs -z3 up -Pd
# Go to the po directory
cd po
# Update the pot file with the new/changed messages
intltool-update ll
# Editing the file, updating the translation! :)
vi ll.po
# Convert the file to UTF-8 (you can skip this if it's UTF-8 already)
mcgconv -t UTF-8 ll.po > ll.po.new && mv ll.po.new ll.po
# Check the file for errors (IMPORTANT! Don't forget this step)
msgconv -cv -o /dev/null ll.po
# Create a ChangeLog entry
vi ChangeLog
# Commit everything (don't forget to add ChangeLog-style commit comment)
cvs commit
# Done!

Learning more
-------------
There's a lot of documentation about cvs available on the web.
http://developer.gnome.org/tools/cvs.html has links to some. Google has
even more links. :-)
If you have trouble using cvs when translating, you're welcome to ask
for help in #i18n at irc.gnome.org at any time.

Happy translating!


Christian