54.2. For the Programmer

54.2. For the Programmer
Prev	Up	Chapter 54. Native Language Support	Home	Next

54.2.1. Mechanics
54.2.2. Message-Writing Guidelines

54.2.1. Mechanics

+ This section describes how to implement native language support in a + program or library that is part of the + PostgreSQL distribution. + Currently, it only applies to C programs. +

Adding NLS Support to a Program

+ Insert this code into the start-up sequence of the program: +

+#ifdef ENABLE_NLS
+#include <locale.h>
+#endif
+
+...
+
+#ifdef ENABLE_NLS
+setlocale(LC_ALL, "");
+bindtextdomain("progname", LOCALEDIR);
+textdomain("progname");
+#endif
+

+ (The progname can actually be chosen + freely.) +

+ Wherever a message that is a candidate for translation is found, + a call to gettext() needs to be inserted. E.g.: +
```
+fprintf(stderr, "panic level %d\n", lvl);
+
```
+ would be changed to: +
```
+fprintf(stderr, gettext("panic level %d\n"), lvl);
+
```
+ (gettext is defined as a no-op if NLS support is + not configured.) +
+ This tends to add a lot of clutter. One common shortcut is to use: +
```
+#define _(x) gettext(x)
+
```
+ Another solution is feasible if the program does much of its + communication through one or a few functions, such as + ereport() in the backend. Then you make this + function call gettext internally on all + input strings. +
+ Add a file nls.mk in the directory with the + program sources. This file will be read as a makefile. The + following variable assignments need to be made here: + +
CATALOG_NAME
+ The program name, as provided in the + textdomain() call. +
AVAIL_LANGUAGES
+ List of provided translations — initially empty. +
GETTEXT_FILES
+ List of files that contain translatable strings, i.e., those + marked with gettext or an alternative + solution. Eventually, this will include nearly all source + files of the program. If this list gets too long you can + make the first “file” be a + + and the second word be a file that contains one file name per + line. +
GETTEXT_TRIGGERS
+ The tools that generate message catalogs for the translators + to work on need to know what function calls contain + translatable strings. By default, only + gettext() calls are known. If you used + _ or other identifiers you need to list + them here. If the translatable string is not the first + argument, the item needs to be of the form + func:2 (for the second argument). + If you have a function that supports pluralized messages, + the item should look like func:1,2 + (identifying the singular and plural message arguments). +
+

+ The build system will automatically take care of building and + installing the message catalogs. +

54.2.2. Message-Writing Guidelines

+ Here are some guidelines for writing messages that are easily + translatable. + +

+ Do not construct sentences at run-time, like: +
```
+printf("Files were %s.\n", flag ? "copied" : "removed");
+
```
+ The word order within the sentence might be different in other + languages. Also, even if you remember to call gettext() on + each fragment, the fragments might not translate well separately. It's + better to duplicate a little code so that each message to be + translated is a coherent whole. Only numbers, file names, and + such-like run-time variables should be inserted at run time into + a message text. +
+ For similar reasons, this won't work: +
```
+printf("copied %d file%s", n, n!=1 ? "s" : "");
+
```
+ because it assumes how the plural is formed. If you figured you + could solve it like this: +
```
+if (n==1)
+    printf("copied 1 file");
+else
+    printf("copied %d files", n):
+
```
+ then be disappointed. Some languages have more than two forms, + with some peculiar rules. It's often best to design the message + to avoid the issue altogether, for instance like this: +
```
+printf("number of copied files: %d", n);
+
```
+
+ If you really want to construct a properly pluralized message, + there is support for this, but it's a bit awkward. When generating + a primary or detail error message in ereport(), you can + write something like this: +
```
+errmsg_plural("copied %d file",
+              "copied %d files",
+              n,
+              n)
+
```
+ The first argument is the format string appropriate for English + singular form, the second is the format string appropriate for + English plural form, and the third is the integer control value + that determines which plural form to use. Subsequent arguments + are formatted per the format string as usual. (Normally, the + pluralization control value will also be one of the values to be + formatted, so it has to be written twice.) In English it only + matters whether n is 1 or not 1, but in other + languages there can be many different plural forms. The translator + sees the two English forms as a group and has the opportunity to + supply multiple substitute strings, with the appropriate one being + selected based on the run-time value of n. +
+ If you need to pluralize a message that isn't going directly to an + errmsg or errdetail report, you have to use + the underlying function ngettext. See the gettext + documentation. +
+ If you want to communicate something to the translator, such as + about how a message is intended to line up with other output, + precede the occurrence of the string with a comment that starts + with translator, e.g.: +
```
+/* translator: This message is not what it seems to be. */
+
```
+ These comments are copied to the message catalog files so that + the translators can see them. +

Prev	Up	Next
54.1. For the Translator	Home	Chapter 55. Writing a Procedural Language Handler