Localising GNOME Applications

So you want to translate GNOME?


GNOME programs are written with the intent of being localisable. This means that a program can be augmented to behave in different ways in different (physical) locations: printed pages in America will be a different size from printed pages in Europe; weather temperatures will be displayed according to Fahrenheit and Celsius scales in different places; and the language the user sees from the program may be the user's native language.

Translation is a major part of this localisation process. The bulk of GNOME translations are performed by native speakers on a volunteer basis. They take sentences in the original English, supply the appropriate translation, and add the file containing this information to the GNOME Git repository so that the next release of the software contains the new language.

This document tries to explain how to get involved in the translation process for GNOME.

Finding your team

First of all, is anyone working on your language already? If so, they should be listed on the GNOME Translation Project team list. Contacting them is the first step. You may also want to take a look at the list of available languages.

If you have found a team for the language you with to localise to, but there is no response from them, contact the GNOME Internationalisation mailing list. Somebody there will advise you what to do.

If there isn't a team for your language, you should also contact the mailing list, in which case you will likely be invited to become the coordinator for that language.

If you have successfully made contact with an active team, you can probably safely skip the next section and move on to the section called “Translating”.

Founding a team

So there isn't a team for your language, but you have bravely volunteered to start one and be its coordinator? Well done!

The role of the coordinator

As the coordinator for your team, you act as the primary contact person for the team and are responsible for organizing the other translators in your team. This includes attempting to prevent multiple translators simultaneously attempting translations of the same file.

Coordinators need to be subscribed to the GNOME Internationalisation mailing list (gnome-18n). This is highly recommended for all GNOME translators, but required of coordinators.

In addition, team coordinators need to keep their language page at l10n.gnome.org up to date. Find your language team page at GNOME Translation Project team list. If any detail is not current, e-mail the GNOME Internationalisation mailing list with the details for the update. You can ask the translators of your team to create an account at the GNOME Translation management website (notice the Log in link at the top-right). When creating an account, ask your members to select your language in the preferences of their account. This adds them to your language team page.

Currently, the GNOME Translation management website allows to reserve a module for translation, submit translated files to this website and other tasks that help to manage the effort among many translators. What is not currently available is the 'committing' (sending) of the translations to the GNOME Git repositories. That is, currently there is an extra step to manually commit the translations.

If any members of your team have Git access, it will likely be you, although you will need to have contributed some translations first before being eligible for an account. See RequestingAnAccount for details.

You should advise your translators to perform their translations through the GNOME Translation management website. Before starting a translation, they should Reserve it so that others do not work on it at the same time. Once they finish, they should Upload the translation so that a person with Git access to the GNOME repositories can add the work.

In a previous version of this document, we asked translators to file a report in GNOME's issue tracker when sending translated files. We do not ask this anymore. The translated files are now sent to the GNOME Translation management website.

Initially, at least, bugs pertaining to your translation team will come in your direction. (You're not likely to get many bugs until your translation becomes used.) As described earlier, your language will have its own component in Bugzilla (note that as of 2019, the Bugzilla issue tracker is being replaced by the Gitlab issue tracker. See https://gitlab.gnome.org/Infrastructure/GitLab/issues/341 ). Translation bugs in the old Bugzilla will be filed against the product "l10n", take a look at the L10N overview page in GNOME Bugzilla to get an idea.

Note that your translators may find it easier to report small bugs or typos at the GNOME Translation management website by simply adding a comment at the affected package. Whether to use this facility for small bugs instead of the issue tracker is a personal preference and a decision by each team coordinator.

The coordinator is often expected to deal with the more technical aspects of translation work, such as plural forms, updating LINGUAS files and generating POT files. (All of which will be covered later. We hope.)

You might also be involved in recruiting more members into your translation team. Many hands make the translations go faster, even though it might mean more work for you!

It is also your responsibility as coordinator to stop being a coordinator when it is appropriate: for example when you no longer have the time to dedicate to the effort that it deserves. If you know that you will no longer be able to perform the coordination role, ask someone to take your place in advance. We ask you to announce the change in coordinatorship to the GNOME Internationalisation mailing list (gnome-18n).

Language codes

To begin with, you will need to find out what your language code is. This is a two- or three-letter code. More popular languages will tend to have two-letter codes, whereas more obscure languages will tend to get stuck with a three-letter one. For languages spoken in more than one country, a translation specific to a country will be followed by an underscore and the two-letter country code capitalized. This can further be appended with an at-sign and more qualifying information. For now, know that language codes typically look like "fr" (French) or "en_GB" (English as used in Great Britain).

If you do not know what the code for your language is, try looking around to see if there are translation efforts for other projects (such as KDE, Mozilla and OpenOffice) in your language — these will (should) use the same code. If that doesn't turn up anything, ask the GNOME Internationalisation mailing list (gnome-18n) for help.

GNOME uses standard codes as defined in ISO standard 639 (for language codes) and ISO standard 3166 (for country codes). The gnome-i18n members will help you identify your language code.

Your language code is used to identify your localisation, for example in the names of locales and files. Once you have your code, you can start translating.

What you will need to start

There are a number of things that will help you immensely in your translation work.

A mailing list

  • You need a forum where your group can talk, preferably in its own language. You can use it for monitoring who is translating what, discuss difficult words and terms, and hammer out a glossary. It might be appropriate to share this mailing list with a translation team for another project (e.g. KDE). It is also a good place to post announcements about your translation. The mailing list might also be used by users of your translations for giving feedback and general discussion.

A web site

  • A web site is good for introducing people to your effort, distributing work, keeping track of who's working on what, and keeping things like glossaries.

A glossary

  • It is important that your translation consistently uses the same terms to avoid confusing users. A standard glossary will help you ensure that you do not refer to one thing by many names. Try not to invent new terms but to reuse existing ones — look for a governing body for your language, or translations used in other projects, or terminology used in Microsoft Windows or Apple OS X. In particular, it's preferable to be consistent with other free desktop environments such as KDE. If you do have to create new terminology, or decide to use one word rather than another, do document your choice (and the reasoning behind it) in your glossary. This saves confusion later. Expect to change some of your initial glossary suggestions after some time translating. It's only once you start translating that you start to notice problems.

    Some teams are the same people as those translating KDE or Mozilla or LibreOffice into the same language. In other teams, there is a separate team for each of these projects. In the second case, it's a very good idea to contact these other teams and find out what they are using, what they have abandoned, and so on.

    A good foundation to base your glossary upon is a combination of the GNOME Documentation Project's Style Guide and the glossary found in the gnome-i18n module in GNOME Git, although the latter needs updating.

    Another option worth to mention is to use Open-tran.eu in order to look up any existing translations of an english word that you want to translate. This service could also be used to search for inconsistencies in translations.

An IRC channel

  • This is a benefit for many of the same reasons as a mailing list is, except that it can be more convenient for certain kinds of discussion, especially for quick queries. It can also be good for helping users of your translation. The Freenode network is an IRC network dedicated to free software-related discussion and would be a suitable place for hosting your channel.

The gettext tools

  • gettext is a package which contains tools for creating translatable strings, turning those strings into a list which can be translated, updating these strings, and converting them into a format the computer can use. Someone on your team (as many as possible really) needs these and to know the basics of how to use them. The package is installed by default on many Linux distributions. Where it is not installed, it is still usually available. You should also look at intltool. This is rather like a front-end to gettext and performs some tasks you need to do as a GNOME translator. It is often available for your distribution, but it is almost always a release or two ahead of whatever is on your distribution. You can find it in GNOME Git.


This is where we get down to it. There are about 44,000 distinct strings which are found in the basic distribution of GNOME 2.26. There are a variety of tactics and methods you can employ, but they all boil down to translating all those strings.

Different approaches

There are different ways of translating. Some teams simple parcel out the “po file” to different people and the members work through them with a text editor and return them to the person who can commit them into GNOME. Other teams use web-based systems. All have advantages and disadvantages.

.po file details are at the end of this page as the longest section. You can jump ahead to the section on .po files if you don't intend to use anything else.

Web interfaces

A web interface generally provides anyone with a list of strings and waits for them to suggest translations for them. Someone periodically sweeps up all the results and feeds them back into Git. The advantage is that only the team co-ordinator and the maintainer of the web interface need to care about how to make .po files. This lets anyone who doesn't have GNOME, a useful editor, or other things help with the translation. One disadvantage is that without being able to see the rest of the file, contributors may not realise how other people are translating applications. If your team is trying to achieve consistency, this can be a problem. Another is that comments from the developer to translators explaining the string are not always shown.

Existing web interfaces include the following:

po files

There is an excellent document available about how to checkout po/ directories, create .pot files, turn them into .po files, and check them back into Git: How to use GNOME Git as a Translator. You must read this. It explains all the details of using the gettext tools. Since this is 90% of working with .po files, you need to know it. We have not repeated it here. We have simply added a few comments which are in addition to it. They do not replace it.

Note that you can obtain .po files from your language's status pages on the GNOME Translation Project website. (See below). Sometimes special characters (non-ASCII) can be garbled doing this, but it is a useful alternative to Git.

A .po file is simply a list of strings from the original program, with spaces for you to put your version in. There is a set of headers at the top, some of which you will have to edit. The Project-Id-Version will become the name of the module. The POT-Creation-Date should be filled in automatically. You must edit the PO-Revision-Date yourself. Language-Team should be your team's language and ideally an email address which will contact one or more of your members. The Content-Type must be UTF-8 and you must make sure that the resulting file is in fact UTF-8 format. On UNIX and UNIX-like systems, the file command will tell you what format it is in. On a machine with all the gettext facilities installed, you can use msgfmt -cv filename.po. If the file is not UTF-8, msgfmt -cv will produce an error message saying so.

You will meet comments in the file. When they say “c-format”, this means that there are strings which the program will fill in itself. For example, the clock applet in gnome-applets has a string to translate of “%H:%M”. You can “translate” this by pasting it straight in. They will be provided by the system clock on the computer. %H is the hours. %M is the minutes.

There is a separate appendix on common C-format strings.

You will also meet messages to translators from the programmer. For example, in gnome-applets, slightly after the message quoted above you will find the comment “translators: reverse the order of these arguments if the time should come before the date on a clock in your locale”.

You will also have to replace menu accelerators: the keyboard shortcuts which can be used instead of clicking on menus. Expect contradictions and collisions in the early days. It is probably most important to do the accelerators for gtk+ first, since they will be in every single GNOME application. Then you can use the remaining letters and try to work out what combinations work the best. Don't worry if you have two or more menu options with the same accelerator. Since version 2.4, GNOME will let you cycle between them.

You will often come across descriptions for GConf/GSettings keys. Usually, each key has both a short and a long description. Strings which are key descriptions can be identified by the fact that they come from files with names resembling .schemas.in.h or gschema.xml.in.

When translating key descriptions, be careful with sample key values, which will be enclosed in double quotes. They should not be translated. For example:

#: src/gnome-terminal.schemas.in.h:70
msgid ""
"Default color of terminal background, as a color specification (can be HTML-"
"style hex digits, or a color name such as \"red\")."
msgstr ""
"Rhagosodiad lliw cefndir y terfynell, fel penodid lliw (gall fod mewn hecs-"
"ddigidau fel yn HTML neu fel enw lliw megis \"red\")." 

In the example, “red” is a sample key value, and must be copied verbatim into the translation. Note that because the double quote character is significant in .po files, it is escaped with the backslash.

If you meet English messages which you cannot understand, don't hesitate to file a bug against the application telling the developer of the problem. Please add the Label "8. Translation" if possible before committing your report. If you meet English messages which you cannot reasonably translate (too complex, not precise enough, etc), file a bug again. Translators as a group file dozens and dozens of these, because translators are the ones who spot them. The earlier you file these the better. When you learn what the message means, you will probably forget about filing the bug. Filing them gets them fixed, and stops other translators having to struggle with the strings.

Don't touch the msgid lines

Do not edit the English strings in the file. If you do that, the programs for merging them into the main application will get confused. Your changes to the English strings will be lost, and your translations may not be incorporated.

Dealing with changes

Unfortunately, software changes, and that includes changes to the translatable content of the software. Strings get added, strings are changed, and sometimes strings are removed. Fortunately, there are tools and procedures which can help you to keep up with changes to the software you're translating.

The status tables

At the Damned Lies about GNOME website you can get status tables for each language translation in GNOME and for each package. Clicking on Languages gives you a list of all language translations of GNOME. Clicking on any of these shows a page with detailed information on the translation status of each GNOME release and it's corresponding documentation for that language. By clicking on the releases you get a status breakdown by package. These pages for the packages contain links to the latest .pot file and the latest .po file (if a start has been made on the translation). You can download these straight from the status pages instead of using Git. You can't upload them that way, but the download facility is very useful.

And all of this is maintained from version 2.14, and the latest stable release, and for the packages which will become the next stable release. At the time of writing (August 2009), 2.26 was the last stable release and 2.28 is under development.

As soon as translations for your language have been committed to Git, your language will acquire its own section in the status tables. You should probably bookmark the pages relevant to your language. They are very very useful.

Your language page will have a URL of the form http://l10n.gnome.org/languages/XX/gnome-2-26 where XX should be replaced by your language code (lower-case). The above URL is for the upcoming GNOME 2.26. If you want to see the stable release of GNOME, adjust the URL accordingly.

Updating changed packages

You will generally discover changes when you update your copy of a module in GNOME Git or when you refresh your browser on your status pages. Again, How to use GNOME Git as a Translator is your guide to the necessary Git commands. If you check out the entire module from Git that you want to translate, you can enter the po subdirectory and run intltool-update xx where XX should be replaced by your language code (lower-case). This command will check the entire module for strings and will update your po file to include the latest strings.

Another option: If you know there are more strings to translate, then you need to generate a new .pot file which contains all the strings to translate and then to merge it with your xx.po file which has a less up-to-date set of translated strings. Generate the .pot file with intltool-update --pot. Merge the two together with msgmerge -o new-xx.po xx.po .pot and try very hard to get those in the right order! Then run msgfmt -cv new-xx.po to see how much work remains. If you are lucky, there will be many many “fuzzy” strings: strings which are so similar to already-translated messages that the msgfmt program has suggested that you use the old translation for the new string.

Fuzzy translations are just that

msgmerge gets fuzzy translations wrong from time to time. Every translator has their favourite suggestion which was badly wrong: my (Telsa's) personal favourite is the suggestion that the translation for “Open window” should be used to translate “Close window”...

Go through your new file searching for instances of the string “fuzzy”. If it is in a comment above a translation that looks correct, then remove the word “fuzzy”. If “fuzzy” is the only word on the line, you can safely remove the whole comment. If you do not remove the word “fuzzy” then the translation will not be used. For example:

#, fuzzy
msgid "Blah blah blah."
msgfmt "La la la."

In this case, if you are confident in the translation, the line with "fuzzy" in it can be removed entirely:

msgid "Blah blah blah."
msgfmt "La la la."

However, you may come across a something like this:

#, c-format, fuzzy
msgid "Very important: %s"
msgstr "Pwysig iawn: %s"

In this case, if you wish to remove the fuzziness, the "c-format" tag must be left intact:

#, c-format
msgid "Very important: %s"
msgstr "Pwysig iawn: %s"

Sometimes a whole set of messages are moved to a new module. This can be particularly disheartening if you had translated them once already and think you now have to do them again. You can save on the work by using the .po file from that module with msgmerge. You can also generate yourself a compendium of messages you have translated which you can keep, edit, and use as a source of suggested translations. You can do this using msgcat, in the form msgcat a.po b.po c.po > compendium. You should check the contents of the compendium before using it for translation, especially for strings of the form “#-#-#-#-#” which indicate conflicts among the original .po files. This feature also means that you can use msgcat to check for inconsistencies among .po files. Once you have created your compendium with msgcat, you can make use of it with msgfmt, as you would any other .po file.

You may find that a whole selection of messages are no longer used in the application. They will be moved down to the bottom of the .po file and left there, commented-out. A # at the start of a line comments it out. It is ignored. Unless there is a very large number of these and they really are getting in the way, do not delete these lines. They may come back into the application. They can also be used by the msgmerge program as a source for finding fuzzy translations. Leave them where they are.

Choosing the first packages to translate

Here are some factors which may help you decide what to translate first.

It is probably best to pick something very small the first time, in order to get used to the translation tools you are using. It is also useful to pick something which is an application rather than a library. This way, you will be able to run the application and see what it looks like. So a small stand-alone application is a good choice.

As soon as you test your application in its new language, you will almost certainly notice that common buttons and dialogue buttons are still in English. This is because they come from some of the libraries and are reused all over GNOME. To get those into your language, you will need to look at GTK+, gvfs, glib and gnome-desktop. These files contain some very difficult strings, but you do not need to do them all yet. Just look for the strings which consistently show up in dialogue boxes. This will help immensely.

The GTK+ package is part of a grouping called “Backends”. It contains about half of the strings in that group. Once you have translated gtk+ you will see a huge jump in your statistics. When you view the statistics page for your language, the package is called “gtk • UI translations ”. If your time is very limited, you may consider leaving untranslated those messages that you find unfamiliar (error messages, properties, etc). The GTK+ "stock" translations are used in many applications, and will give you good motivation with minimal work at the start. An example of these “stock” messages (stock: they are reused in many applications) are things like “OK”, “Cancel”, “Open”, “Save”, “Print”, “Warning”, “Undo”, “Preferences” that are used in many applications.

Another very useful and small file to translate is xdg-user-dirs which is outside the GNOME project. This package contains common directories like "Videos", "Pictures", "Documents" etc. It can have a big impact with a small amount of work.

Some strings used in the Epiphany web browser come from WebKitGTK. So even when you have completed Epiphany, you may occasionally meet messages supplied by WebKitGTK which are not translated. These messages can be translated in WebKitGTK module.

Choosing the last packages to translate

The so-called "Development tools" are modules that are needed by software developers only and not by average users. Software developers are often able to speak English hence you should give these modules a low priority.


Testing your translations are very important. This is where you start realising that one of you has used one word for “install” and someone else has used another; or that that word “body” was referring to something other than a human body.

The more testing you can do, or persuade your friends to do, the better. Even someone who isn't bilingual can help review the translations.

Testing a translation of software

If you have a reasonably up-to-date version of GNOME on a computer to which you have root access, you can test your translations on your machine and view them in context. This is strongly to be recommended. The machine will need a message object (.mo) file which you can create with the msgfmt -cv command. Run that on your po file, and you will find a file called messages.mo in the directory. This should be placed in the /usr/share/locale/XX/LC_MESSAGES/ directory (where XX is the code for your locale) and given the name of the program. Examples might be metacity.mo or nautilus.mo. Sometimes the program name requires a version number on it. Unfortunately, there is no easy way to work out what the name of the .mo should be for a given package. You will need to look at already-existing filenames in a sister directory to see what they use and copy those. Have a look around the different locales in /usr/share/locale/ and you should find good examples to copy.

Then run the application. Changing the .mo file will probably cause the application to crash, so save your work first; and if you are putting a gnome-terminal.mo there, make sure you are ready for the crash :) Once the file is in place, the app will be fine. It's just the act of updating the file which can cause problems.

Note that /usr/local/share/locale/XX/LC_MESSAGES/ may be used for locally built packages, so you can try to put the .mo file there if you are unable to see your translation otherwise.

The locale needs to exist

The above will only work if the locale exists on your computer. If it does not, you will need to create it. This is simplest on Debian: there is a command for it. The procedure varies on other distributions, unfortunately, and is well outside the scope of this document. Patches are welcome. :)

Once you have figured out how to install your translations onto a machine, pass the instructions out far and wide to people who might be interested in testing them out. Other people always spot more mistakes than you can. They may also be inspired to help!

Testing a translation of help files

There are two ways of writing help files: Mallard (the newer, better way), and the older DocBook method, which might still be used for your module. Damned Lies will indicate Mallard modules with an icon of a duck. These are probably more useful to translate in the long term, since they are less likely to be rewritten soon.

Testing your translation is similar for both. Here the method for Mallard is shown:

Move into the help directory and make a temporary directory to build your translated help in:

cd help
mkdir -p tmp

Change into the directory where the .page files are:

cd C

Now generate a translated file for each English file (assuming your file is in ../af/af.po):

for i in *.page; do xml2po -m mallard -p ../af/af.po $i > ../tmp/$i; done

Now open Yelp with the directory where your files are:

yelp ../tmp

This way you won't see images, which will make it easy to review alternative text for the images. You can insert the images by copying C/figures/ (or similar) into your temporary directory.

Editors and editor tricks

A number of editors have special modes for editing .po files, and will drop you into the appropriate mode automatically.

Ensure that your editor is writing in UTF-8 format. If the file is not this format, things in GNOME Git will break.

Editors known to deal with UTF-8 well: Emacs Vim GEdit

For vim, things we have found useful to put into .vimrc are:

set fileencodings=utf-8
" A vim macro that makes control-E copy the msgid to the msgstr:
map <C-E> :s/msgid "\(.*\)"\nmsgstr ""/msgid "\1"<C-V><CR>msgstr "\1"/<CR>

There is a plugin for editing .po files in vim which has several other useful tricks. It is available on the Vim website as, unsurprisingly, po.vim

GNU-Emacs has an entire PO mode.

You can find an (incomplete) comparison of available gettext oriented translation tools there: http://kbondarava.blogspot.com/2012/02/localization-which-tools-to-use.html

Other people are welcome to fill in more tricks for editors, ideally as dotfile instructions.

Other hints

There are some things we have learned from bitter experience, and we are including them here so other people don't do it.

  • Don't leave it ages to get stuff on the branch. We fell for this. However long it takes to check out the branch and update your translation, and however painful it is, if you intend to do both master and branch, apply the changes to both. If you don't, you will meet a day when you spend hours and hours and hours doing nothing but feeding stuff back onto the branch.
    If you are on a slow connection or a metered connection, check the branches out into a separate directory rather than flipping between branch and master. It might take longer the first time, but it saves a lot of time in the long run.

  • Automate as much as is safely possible. For example, when you are adding new translations, you will type the same three lines into the main Changelog about adding your locale to LINGUAS something like fifty times. Make a file which says it all already, and update the date daily. And then just include it with an editor macro. It's a lot better than typing it in fifty times. Use shell aliases for frequently used commands.

  • Find a language enthusiast! You will meet all manner of strange strings to translate, from the detailed spreadsheet terminology of Gnumeric to your language's equivalent of the English “The quick brown fox..” sentence which is used in the font selector because it includes every English letter. You will need to find or invent your own alternative which contains the letters your language uses. (This may be harder for Japanese and Chinese...)
    If your language has an accepted set of translations of new terminology, be aware of it, even if you don't like it. Be prepared to justify why you didn't use some “official” terminology...

  • Expect the occasional deliberately silly string. You will meet in-jokes from GNOME hackers as you go through more and more files. The GEGL, for example, may be a code library, but it is also the abbreviation for Genetically Engineered Goat, Large, and is just a silly joke that crops up in various places in GNOME. There is no need to translate it. There is also a selection of bizarre “hints” in one of the aisleriot files.
    Accept them. Put up with them. They are part of what makes GNOME fun, although it's difficult to believe that when you've just worked your way through four dictionaries trying to work out what the word might be...

  • The GNOME Internationalisation mailing list (gnome-18n) and the #i18n IRC channel can be either really busy (gnome-i18n) or almost always quiet (#i18n), but there are people on them who have almost certainly met these things before, and can suggest ways to deal with them. Use them.

  • It's really easy to omit the underscores which will turn a key into a keyboard shortcut in a menu. You can check whether the number of underscores in the msgids and the msgstrs match with the command msgfmt --check-accelerators=_ (but note that once you have filled the translator_credits one in there will always be one that appears to be missing).

  • Avoid using characters with accents as accelerators. Currently, there is an issue when you set an accelerator to a character such as Á, Å, ᾈ. (character with accents). The problem is that the user would need to press Alt and then the key sequence to produce this character with accent. If, for example, your keyboard layout requires dead keys, then it is currently not possible to type those characters while Alt is pressed. For more, see Keyboard accelerators and accents.

  • Test, test, test. Whilst it is hard to get everything localised on your machine, it is very easy to install your own latest translations for at least some applications. Do this. It will really help.
  • Create a tarball of completed translations. (Another good candidate for automation.) Put them up on the web with very simple walk-through steps which let other people install them. This gets you feedback (and help) much earlier than waiting for a distribution to ship them will. The instructions for installing will unfortunately differ for very nearly every distribution. But the results are worth it.



  • Git: the system used to maintain the repository of GNOME code in a central place.


  • The abbreviation of internationalisation (the initial and final letters of the word and then eighteen letters between them): the process of ensuring a program comes in a form which can be localised.


  • The abbreviation of localisation (the initial and final letters and then ten between them): the process of making a program work in a particular location. It includes both translating messages and tweaking such things as measurements, currency symbols and temperature scales.



A. Special characters in po files, and one special string

There is a separate appendix about C-format strings. Here is a list of other characters and situations which can cause problems.

Escape-able characters

  • Some characters will be interpreted by the programs which operate on .po files and thus need to be escaped with a backslash in front of them.

    The most common character for this is a double-quote character like " .

Formatting marks

  • You may come across the combinations \n or \t. These mean newline and tab. You do not have to put the same number of these into your translation, but if there is one of these at the start (or end) of the string, you must include one at the start (or end) of your translated string.

Angle brackets and ampersands in GConf files

  • There are one or two modules where XML is used heavily. GConf is the most notable. XML treats the characters <, > and & as special. You can not just include them in your translation. You must specify them as entities. < is represented as < > is represented as > & is represented as & FIXME: I've sure we've met this. But where? And does it apply to all .in.in.h files too?


  • “TRUE” and “FALSE” show up in gtk+ and in Gconf and in a lot of files generated by Glade. (These will have a name ending in .glade.) Do not translate them. Programs expect to see them and will be confused if they don't.

There is also one very special string in the .po file: the msgid of translator_credits. This will show up when someone running the application in your language looks at the credits by following the Help->About path in the application. They will see a Translation option. In that will be the contents of this translator_credits. This is where you put your name(s), so the world can see. The typical format is to put a list of names and email addresses on separate lines, with the URL of any team page. For example:

msgid "translator_credits"
"Telsa Gwynne <hobbit@aloss.ukuug.org.uk>\n"
"Dafydd Harries <daf@muse.19inch.net>"

Don't forget to do this one :)

B. Some C-format strings to leave alone — or to re-order

This is a brief list of C-format strings you may need to know about.


  • This represents a string. An example is in nautilus:

    #: components/emblem/nautilus-emblem-view.c:834
    #, c-format
    msgid "The file '%s' does not appear to be a valid image."
    msgstr ""

Strings containing such C-format sequences are marked with the "c-format" tag, like in the example. Be aware that where there are two instances of one of these, they are not necessarily the same string. Another nautilus example:

#: components/hardware/nautilus-hardware-view.c:483
#, c-format
msgid "Uptime is %d days, %d hours, %d minutes"
msgstr ""

If you need to re-arrange them to make them make sense, you can do that. In English, this is common:

#, c-format
msgid "%d out of %d"

This might come out as “10 out of 100”. If your language wants to say “Out of 100, 10”, you can reverse them like this:

#, c-format
msgid "%d out of %d"
msgstr "Out of  %2$d, %1$d"

Original Authors

This guide was originally written by:

Telsa Gwynne

Dafydd Harries


This document can be redistributed and/or modified under the terms of the GNU General Public License; either version 2 of the license, or (at your option) any later version. The full text of the license can be found at http://www.gnu.org/copyleft/gpl.html.



TranslationProject/LocalisationGuide (last edited 2020-03-27 15:41:00 by AndreKlapper)