Re: [PATCH v12 11/13] bisect--helper: `bisect_next_check` & bisect_voc shell function in C

Junio C Hamano <gitster@pobox.com> writes:

I recall you saying that you are not familiar with i18n. As it is a good skill to have outside the context of this project, let's do a quick primer. GSoC is a learning experience ;-).

There is a runtime function "gettext()" that takes a string, which is typically a printf format string, and gives another string. You feed your message in the original language, meant to be used in the C locale, and the function gives it translated into the end-user's language, specified by environment variables like $LC_MESSAGES.

Since it is too cumbersome to write gettext() all the time, _() exists as a short-hand for it. So running this

	printf(_("Hello, world\n"));

would look up "Hello world\n" in database for the end-user's language, and shows the translated message instead.

By scanning the source text, you can extract these constant strings passed to gettext() or _(). This is done by the i18n coordinator with the "msgmerge" program. By doing so, we learn "Hello, world\n" must be translated, and then ask i18n team to translate it to their language. The result is what we have in the l10n database. They are in po/*.po files in our source tree.

Sometimes, the message you want to be translated may be in a variable, e.g.

        void greeting(const char *message)
        {
                printf(_(message));
        }

        int main(int ac, char **av)
        {
                int i;
                const char *message[] = {
                        "Hello, world\n",
                        "Goodbye, everybody\n",
                };
                for (i = 0; i < ARRAY_SIZE(message); i++)
                        greeting(message[i]);
        }

And scanning the source would not find "Hello, world\n" or "Goodby, everybody\n" must be translated. We do not want to do this:

                ...
                const char *message[] = {
*BAD*                   _("Hello, world\n"),
*BAD*                   _("Goodbye, everybody\n"),
                };
                ...

because we do *NOT* want to call gettext() there (we call the function at runtime inside greeting() instead). We use N_() to mark such messages, like so:

                ...
                const char *message[] = {
*GOOD*                  N_("Hello, world\n"),
*GOOD*                  N_("Goodbye, everybody\n"),
                };
                ...

The N_() macro is a no-op at runtime. It just is there so that "msgmerge" can notice that the constant string there is something that needs to be thrown into the l10n database.

As a concrete example:

this is such a use of N_(). You want to keep untranslated message in the git_bisect_helper_usage[] array, to be given to gettext(), or more likely its short-hand _(), when these usage strings are used, and make sure these strings will be in the l10n database so that translators will give you translations to them to be used at runtime.

This one wants to call gettext() function to give fprintf() the translated warning message. It should be _().

Just like this one.