From a4d698792a9b8e8469f28efed54a4ba2ce177438 Mon Sep 17 00:00:00 2001 From: Sven Neumann Date: Wed, 3 Sep 2008 10:06:24 +0000 Subject: [PATCH] removed lots of outdated information directed at developers and only kept 2008-09-03 Sven Neumann * README.i18n: removed lots of outdated information directed at developers and only kept the most important hints for translators. svn path=/trunk/; revision=26840 --- ChangeLog | 5 ++ README.i18n | 224 +++++++--------------------------------------------- 2 files changed, 32 insertions(+), 197 deletions(-) diff --git a/ChangeLog b/ChangeLog index 5db9c43183..bd655c7b8c 100644 --- a/ChangeLog +++ b/ChangeLog @@ -1,3 +1,8 @@ +2008-09-03 Sven Neumann + + * README.i18n: removed lots of outdated information directed at + developers and only kept the most important hints for translators. + 2008-09-02 Sven Neumann * app/plug-in/gimppluginshm.c: if INVALID_FILE_HANDLE is undefined, diff --git a/README.i18n b/README.i18n index 8f52b2e9cf..5dcb99586e 100644 --- a/README.i18n +++ b/README.i18n @@ -1,170 +1,28 @@ -This document exists to document the important things to care -for because of locale support. It is aimed at developers and -translators. If you are a translator, you can skip the first -sections, but you definitely want to read sections 5 - 9. - - Table of Contents - - 1. Why localisation? - 2. How - 3. Deep inside ... - 4. Some magic ... - 5. Tools and how to use them - 6. Gimp is different - 7. Adding additional textdomains - 8. Tip of the Day messages - 9. How to contribute - 10. And more ? +This file contains some important hints for translators. -1. Why localisation? +The current status of the GIMP translation can be checked at - Many persons from many countries start to get used to Linux. - Unfortunately not everyone is able to understand English. But - even those people sometimes like to use good and free software - without using a dictionary to get the unknown words. - So why not simply localise the software to make it available to - the mass which isn't wholly English native? Of course this also - eases the migration from PhotoX to GIMP. :)) - -2. How? - - GNU provides a very nice package called gettext. This one offers - the possibility to translate chosen messages from the native language - of the program into that one of the users if a necessary catalog is - provided. Gettext therefore provides some easy tools to create and - maintain such catalogs and a few functions which can be called by the - program to enable automatic translation at runtime. The program gets - linked to the gettext library or glibc2 which already provides that - functionality and everything is fine. - -3. Deep inside... - - GIMP provides header files called gimpintl.h and stdplugins-intl.h in - the libgimp directory which check whether gettext is available on the - system which GIMP is compiled on and will deactivate language support - if it's not. - - If the gettext system is there it will declare 3 functions which will be - described below. - -3.1 _() [more correctly: char * _( char * )] - - This one is a macro for the function gettext(). You can wrap any text - with it that is allowed to be a return value of a function. If you - use it then libintl will try to translate it into the native language - of the user according to his/her environmental settings. - The gettext() function will do a lookup in the hashed catalog which - contains all the translated texts. - - - If it is found a pointer to the string will be returned to the caller. - - If not, the caller will receive a pointer to the original string. - - This way it is ensured that there isn't any harm caused to the program - if no useful catalog is installed. - - Please note that it is important to use _() directly (and not gettext()) - for simple messages because of reasons that will be mentioned below. - - NOTE: I know some of the developer like short functions like _() but - for a better source understanding I suggest to use it consistently only - for text (like _("That's text!")) and not for variables (like _(text)). - Use gettext(text) instead. + http://l10n.gnome.org/module/gimp -3.2 N_() [more correctly: const char * ( const char * ) ] +Translation of the GNU Image Manipulation Program is handled by the +GNOME Translation Project (see http://l10n.gnome.org/). If you want to +help, we suggest that you get in touch with the translation team of +your language (see http://l10n.gnome.org/teams/). - This one is a macro for the function gettext_noop(). As you can see - and guess it doesn't really do anything in the programm i.e. it is a - dummy macro but nevertheless important. As it isn't possible to call - functions in a structure as seen here: - struct blurb - { - _("This won't work\n"); - } +GIMP is different - you have to do it in some other way. In GIMP such structures are - often used to create menus or similar things very simply. Here you - have to use the dummy to allow the generation of the template catalog - which will be described below. This one doesn't do anything but it - marks the text as important to the xgettext extractor. - - The text has to be translated manually with the next function. - -3.3 gettext() - - This function is the same as that macro in 3.1. But there is one big - difference: The _()'s and N_()'s are the only expressions which get - parsed by the template generator. - If you have strings that should be translated but are unfortunately - in a structure you have to do that on your own which means that you - have to parse the fields with the messages in a loop and translate - the texts with this gettext() function. - - Please note that it may be necessary to free or allocate memory in - this case! - -4. Some magic... - - As you have seen we only did the programming part until now but this - isn't all by far. To use catalogs we'll have to create them. Now - there are 3 different files which are importart: - - gimp.pot: - - This one is the so called template. It contains the messages which - are extracted from the sources and empty fields which have to get - filled by the author. It is used to start a new catalog or to update - the an already available one. - - The Makefile will automatically call the program gettext which will - extract all messages that are wrapped by a _() or a N_() (but NOT - gettext()) and concat them to this template. - - [language].po: - - This file has to be an edited gimp.pot and contains the original - messages plus the translated ones. This file will be delivered - together with GIMP and is the base for the final catalog. - - [language].mo: - - This file is a compiled version of [language.po] which will be - automatically compiled by the Makefile system and installed in the - locale directory of the system. It contains everything that the .po - file contains except not translated messages, comments and other - overhead. For maximum speed it is also hashed to allow gettext a - faster search. - -5. Tools and how to use them - - As mentioned the to be translated strings are extracted directly from - the source and written to the template. - - I guess many of you will now ask if it is necessary to add new - strings directly to the template or if there's a tool to achieve - that. I think I can calm down those of you who fear lots of had work - just to update the language files. There's a program called msgmerge - which will add all strings that are in the template but not in the - uncompiled catalog to it. Msgmerge does this job very nicely and also - tries to use some kind of fuzzy logic method for already translated - strings for possible reduction of translators work: If an original - string seems similar to a new one and it already has a translation, - it will be taken over to the new catalog together with a remark that -this one may not necessarily fit. - -6. Gimp is different - - Gimp is a complex application which has a bunch of scripts and + GIMP is a complex application which has a bunch of scripts and plug-ins that all want to be internationalized. Therefore there is - not one catalog but many. For a full translation of GIMP's UI, - you will have to add translations for the following catalogs: + not one catalog but many. For a full translation of GIMP's UI, you + will have to add translations for the following catalogs: po/gimp20.po -- the core po-libgimp/gimp20-libgimp.pot -- the libgimp library - po-python/gimp20-python.pot -- the pygimp plug-ins po-plugins/gimp20-std-plugins.pot -- the C plug-ins + po-python/gimp20-python.pot -- the pygimp plug-ins po-script-fu/gimp20-script-fu.pot -- the script-fu scripts po-tips/gimp20-tips.pot -- the startup tips @@ -172,32 +30,12 @@ this one may not necessarily fit. gimp-perl has been moved into it's own Subversion module called gimp-perl. - The version of GIMP you are holding in your hand uses GTK+-2.0. - GTK+-2.0 requires that all strings are UTF-8 encoded. Therefore to - make internationalisation work, po files need to be UTF-8 encoded. If - your editor doesn't support UTF-8, you need to convert it to an - encoding your editor can handle and convert it back to UTF-8 before - commiting your changes back. The gnome-i18n module in Subversion has - some scripts that help with this task, but it can also easily done - using iconv. -7. Adding additional textdomains +GIMP Tips dialog - Third-party plug-ins (plug-ins that are not distributed with The - GIMP) can't have their messages in the gimp-std-plugins textdomain. - We have therefore provided a mechanism that allows plug-ins to - install their own message catalogs and tell GIMP to bind to that - textdomain. This is necessary so that GIMP can correctly translate - the menu paths the plug-in registers. Basically the plug-in has to - call gimp_plugin_domain_add() or gimp_domain_plugin_add_with_path() - before it registers any functions. Have a look at the script-fu - plug-in to see how this is done in detail. - -8. Tip of the Day messages - - In addition to message catalogs Gimp provides a file with tips that - are displayed in a Tip of The Day window. This file is in XML format - and can be found in the tips directory. The english tips messages are + In addition to message catalogs GIMP provides a file with tips that + are displayed in the Tips dialog. This file is in XML format and can + be found in the tips directory. The english tips messages are extracted from gimp-tips.xml.in so translators can use the usual tools to create a .po file that holds the translations. All translations are then merged into gimp-tips.xml with language @@ -208,27 +46,19 @@ this one may not necessarily fit. message catalog that needs to be translated correctly. For a german translation of the tips this would look like this: - #: app/gui/tips-parser.c:158 + #: ../app/dialogs/tips-parser.c:188 msgid "tips-locale:C" msgstr "tips-locale:de" -9. How to contribute - Any help with translations is appreciated. If you want to help, - please get in contact with the people from the GNOME Translation - Project who coordinate all translation efforts in the GNOME - Subversion tree. They have a nice web-page at - http://developer.gnome.org/projects/gtp/. - -10. And more? - - We hope we mentioned everything that is worth it and hope that this - document will clarify some things. If it doesn't please write us a - mail. This text of course contains errors, so if you find one tell - us... - - -Happy Gimping. - Daniel Egger - Sven Neumann +Localization of third-party plug-ins + Third-party plug-ins (plug-ins that are not distributed with GIMP) + can't have their messages in the gimp-std-plugins textdomain. We + have therefore provided a mechanism that allows plug-ins to install + their own message catalogs and tell GIMP to bind to that + textdomain. This is necessary so that GIMP can correctly translate + the menu paths the plug-in registers. Basically the plug-in has to + call gimp_plugin_domain_add() or gimp_domain_plugin_add_with_path() + before it registers any functions. Have a look at the script-fu + plug-in to see how this is done in detail.