Various parts of the CAPS universe are interacting with the user. At this point it is important to speak his or her language. At least in the case of a failure - to provide the help to recover.

Thus, all string outputs should be marked to have them collected into a single translateable file. This is the work of the gettext package: it extracts marked strings in the source files and writes them into a POT file.

The string markers are defined in src/libcapsbase-local.h to make the C compiler happy. To make gettext happy, the same set is used in po/Makevars (refer variable XGETTEXT_OPTIONS) to let gettext extract the correct strings.

Two markers are in use: the simple underline (e.g. '_') and the 'NLS_' marker. Both are required due to different usage at runtime.

The underline is used everywhere in printf calls e.g. active code. From the C compiler's point of view it expands to a dgettext() call, which tries to translate the given string inside the printf call.

The 'NLS_' is used in passive code, e.g. structure defines for example. They need a special treatment somewhere else in the code to be translated when used. So, 'NLS_' doesn't do anything activly, it really only marks the string to have it available on demand. The 'NLS_' macro expands to nothing from the compiler's point of view. This marker is only used by gettext to extract the string and add it to the collection of translation strings.

Examples:

The printer driver outputs a starting information:

caps_print_info(_("SPL driver is starting\n"));

This is an active piece of code and at run-time the caps_print_info() calls recieves the string argument translated via dgettext() (if a translation is available).

The printer drivers might define this structure somewhere:

static const struct caps_ppd_selection_entry selection = {
   .option = "AUTO_CUTTER",
   .description = NLS_("Automatic Cutter"),
   .value = "AUTO",
};

This structure is forwarded into libcapsprovider via caps_pp_instance_runtime_setup(). From the content of this structure a PPD file is generated and string from the .description member is shown to the user and thus, should be translated into the user's native language. This is done inside libcapsprovider (to be more precise in libcapsppd). To enable caps_pp_instance_runtime_setup() doing so, this string must be available in the translation list. Thus, 'NLS_' sorts out this string and make it available.

Note: The caps_pp_instance_runtime_setup() API first tries to translate this string via the caller's translation list. If this fails, it tries to use its own translation list. If this fails as well, it uses the plain string.