/!\ GNOME uses Git instead of SVN nowadays. This wikipage only exists for historical reasons. See the Git How-To for the current instructions.

How to use GNOME SVN as a translator

As a frequent GNOME translator, you can apply for a SVN account. These instructions are for those who have received 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 "xy" as an example below. Replace it with your own language code.

Introduction

With a non-anonymous GNOME SVN (Subversion) 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 xy.po without asking for permission, but here are a couple of things you should remember to do before any xy.po commit:

  • Make sure the file is encoded in UTF-8 (for GNOME2/GTK2 software)
  • Make sure the file passes the "msgfmt -cv xy.po" test
  • Add an entry at the top of the "ChangeLog" file in the po directory

Look at the other entries in the ChangeLog for how the format looks like. Remember to use UTF-8 in ChangeLog files (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.net>

        * sv.po: Updated Swedish translation.

If you use Emacs, the ChangeLog entry is most easily generated by opening the .po file and pressing "C-x 4 a".

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). There are also other scripts available to do this. From eazel-hacking, prepare-ChangeLog.pl.

Using Subversion

Subversion official documentation is very good. The "How to Read" chapter will explain what chapters you need to read before GNOME SVN. Getting the most out of Subversion in GNOME, is a general-purpose short guide for SVN with GNOME, but the relevant part is here.

To check out the latest version of a module, from a shell:

svn co http://svn.gnome.org/svn/[module]/trunk [module]

You should replace [module] with the name of the module you want. If you want the check-out to be put in a folder that is not the same as the module name, specify your own folder name instead of the second [module] instance.

Registered GNOME developers will be able to use their SSH key to authenticate themselves to the Subversion server so that they make also commit changes back to the Subversion repositories. They will use a slightly different URL to check out and deal with Subversion modules:

svn co svn+ssh://[login@]svn.gnome.org/svn/[module]/trunk [module]

In this case, if your local login is not the same as your GNOME developer login, you will also need to specify it in the URL.

Subversion allows you to isolate changes onto a separate line of development, known as a branch. Quite often in GNOME, there are stable and unstable branches of development for a given module - as a result, the main trunk [also known as 'trunk'] may not be suitable for your needs. Stable branches in GNOME Subversion are generally a mixture of lowercase alphabetic & numeric characters separated by dashes i. e. of the form

[module/project]-[MAJOR]-[MINOR]

where major, minor are version numbers. For example

gnome-2-0
gtk-2-0

In Subversion, branches and tags are simply stored in subdirectories. You can check out a branch using the following command:

svn co http://svn.gnome.org/svn/[module]/branches/[branch name] [local folder]

For a list of the available branches for a given module, construct and view the following URL in your browser:

http://svn.gnome.org/viewcvs/[module]/branches

The following example will check out gnome-utils trunk and 'gnome-2-0' branch, creating 'gnome-utils' and 'gnome-utils-stable' in your current directory

svn co http://svn.gnome.org/svn/gnome-utils/trunk gnome-utils
svn co http://svn.gnome.org/svn/gnome-utils/branches/gnome-2-0 gnome-utils-stable

Maintainers 'tag' their module to mark releases in GNOME Subversion. Tags in GNOME Subversion are generally a mixture of uppercase alphabetic & numeric characters separated by underscores i. e. of the form

[MODULE]_[MAJOR]_[MINOR]_[MICRO]

where MAJOR, MINOR and MICRO are version numbers. For example

GTK_2_0_6
GNOME_UTILS_2_0_2

For a list of the available tags for a given module, construct and view the following URL in your browser:

http://svn.gnome.org/viewcvs/[module]/tags

Subversion was designed so that whenever there were any changes in the source code, you didn't need to remove your sources and re-check out. The following command syncs up your code with what is stored in the Subversion repository

svn update

When you update, you will notice a letter leading each file that is updated or not. These letters have the following meaning

U

Updated from the server and sent as a completely new file

P

Updated from the server and sent as a diff which your client used to patch the file

A

File was added

R

File was removed

C

There is a conflict

M

File has been locally modified

?

File in local repository Subversion knows nothing about.

If you have conflicts, you must resolve these, in general, before being able to rebuild the source code.

If you want to see the changes in a file, instead of listing the changed files, you should use:

svn diff [file]

If you omit the file, all files in the current directory will have their differences printed.

JHBuild

Translators don't have to compile the module before committing a translation -- in fact, they don't even have to check the whole module out (see below). If, however, you want to build your module to test the translation, you should consider using JHBuild, which enables developers to build a complete GNOME environment from SVN code without interfering with the regular GNOME installation.

To use JHBuild you will have to install the dependencies following JhbuildDependencies and then JHBuild.

If you have issues, please check the JhbuildIssues page.

Dial-up Connection

A single module can have from 6 to 150Mb, and a complete GNOME 2.20 checkout will have 1,5 Gb (trunk only, not counting branches and tags). Once in your hard disc, they occupy twice the space, because SVN stores a version in the .svn directories for faster comparisons with your modified files. The good news is, you don't have to check out a full module set (for example GNOME 2.20) or even a single module a time in order to commit translations.

You can use the new version of Subversion (still in development) to checkout only one file. The workaround is:

svn co --depth=empty [URL] [local folder]
svn up [directory]/[file]

Anytime you can fetch the rest of files using

svn up --depth=infinity

Committing interface translation

How to update a translation

Let's go through all the steps of updating an existing "xy" 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 svn:

svn up
  • Go to the po directory:

cd po
  • Update the po file with the new/changed messages:

intltool-update xy
  • Editing the file, updating the translation:

vi xy.po
  • Convert the file to UTF-8 (you can skip this if it's UTF-8 already):

msgconv -t UTF-8 xy.po > xy.po.new && mv xy.po.new xy.po
  • Check the file for errors (IMPORTANT! Don't forget this step):

msgfmt -cv -o /dev/null xy.po

vi ChangeLog
  • Commit everything (don't forget to add ChangeLog-style commit comment):

svn ci 

Done!

How to add a translation

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

  • Add "xy" to the list of language codes in the module's po/LINGUAS file (See GnomeGoals/PoLinguas)

  • Add an appropriate entry to the "ChangeLog" file in the same directory

  • Make sure the po file is not executable ("chmod -x xy.po")
  • Remember to add the file ("svn add xy.po")

Let's go through all the steps of adding a new "xy" translation in an example. We'll use gconf as the example below.

We note that gconf has several branches for stable releases, while development happens in SVN Trunk. For various reasons it's preferable to first add the new translation to TRUNK and then on the branch when adding translations to modules that use a branch. Because of this we will first add the new translation to gconf TRUNK:

  • Checkout it since we didn't have it checked out already:

svn co [URL]/gconf/trunk gconf
  • Go to the po directory:

cd gconf/po
  • Create the pot file:

intltool-update --pot
  • Rename the pot file to xy.po:

mv GConf2.pot xy.po
  • Editing the file, creating the translation:

vi xy.po
  • Convert the file to UTF-8 (you can skip this if it's UTF-8 already):

msgconv -t UTF-8 xy.po > xy.po.new && mv xy.po.new xy.po
  • Check the file for errors (IMPORTANT! Don't forget this step):

msgfmt -cv -o /dev/null xy.po
  • Make sure the file doesn't have executable permissions:

chmod -x xy.po
  • Mark the file for addition (IMPORTANT! Don't forget this step):

svn add xy.po

vi ChangeLog
  • In case file LINGUAS exists: Add "xy" to the file LINGUAS:

vi LINGUAS
  • Go to the parent directory:

cd ..
  • In case file LINGUAS does not exist: Add "xy" to the ALL_LINGUAS line of configure.in:

vi configure.in

vi ChangeLog
  • Commit everything (don't forget to add ChangeLog-style commit comment):

svn ci

Please note that forgetting to do the steps above marked important may break things and cause the module not to build anymore, a situation that should be avoided at all times. This is especially true for committing po files that contain syntactic errors by forgetting to check the file with msgfmt first, or forgetting to add a po file to SVN by forgetting the svn add step while at the same time specifying that it should be used in the LINGUAS file (or in case the LINGUAS file does not exist: in the ALL_LINGUAS line of configure.in). Please remember to do these steps.

And now, since gconf used a branch, let's continue with the branch (skip the following steps if the module doesn't use a branch). In this example, we check out the gnome-2-2 branch of gconf to the local directory gconf-gnome-2-2:

  • Start by going to the parent directory where you want the module stored:

cd ..
  • Checkout the branch since we didn't have it checked out already:

svn co [URL]/gconf/branches/gnome-2-2 gconf-gnome-2-2
  • Go to the po directory:

cd gconf-gnome-2-2/po
  • We have already created a translation in HEAD; let's copy that and use it as a starting point for our translation here in the branch:

cp ../../gconf/po/xy.po .
  • Update our po file with the new and changed messages:

intltool-update xy
  • Editing the file, updating the translation:

vi xy.po
  • Convert the file to UTF-8 (you can skip this if it's UTF-8 already):

msgconv -t UTF-8 xy.po > xy.po.new && mv xy.po.new xy.po
  • Check the file for errors (IMPORTANT! Don't forget this step):

msgfmt -cv -o /dev/null xy.po
  • Make sure the file doesn't have executable permissions:

chmod -x xy.po
  • Mark the file for addition (IMPORTANT! Don't forget this step):

svn add xy.po

vi ChangeLog
  • In case file LINGUAS exists: Add "xy" to the file LINGUAS:

vi LINGUAS
  • Go to the parent directory:

cd ..
  • In case file LINGUAS does not exist: Add "xy" to the ALL_LINGUAS line of configure.in:

vi configure.in

vi ChangeLog
  • Commit everything (don't forget to add ChangeLog-style commit comment):

svn ci 

Done!

If you have trouble using svn when translating, you're welcome to ask for help in the #i18n channel on irc.gnome.org at any time.


CategoryGnomeI18n

TranslationProject/SvnHowTo (last edited 2010-01-18 20:30:56 by AndreKlapper)