2.3.1 Locale Names

A locale name usually has the form ‘ll_CC’. Here

• ‘ll’ is an ISO 639 two-letter language code. For some languages, a two-letter code does not exist, and a three-letter code is used instead.
• ‘CC’ is an ISO 3166 two-letter code of a country or territory.

For example, for German in Germany, ll is de, and CC is DE. You find a list of the language codes in appendix Language Codes and a list of the country codes in appendix Country Codes.

You might think that the country code specification is redundant. But in fact, some languages have dialects in different countries. For example, ‘de_AT’ is used for Austria, and ‘pt_BR’ for Brazil. The country code serves to distinguish the dialects.

Many locale names have an extended syntax ‘ll_CC.encoding’ that also specifies the character encoding. These are in use because between 2000 and 2005, most users have switched to locales in UTF-8 encoding. For example, the German locale on glibc systems is nowadays ‘de_DE.UTF-8’. The older name ‘de_DE’ still refers to the German locale as of 2000 that stores characters in ISO-8859-1 encoding – a text encoding that cannot even accommodate the Euro currency sign.

Some locale names use ‘ll_CC@variant’ instead of ‘ll_CC’. The ‘@variant’ can denote any kind of characteristics that is not already implied by the language ll and the country CC. It can denote a particular monetary unit. For example, on glibc systems, ‘de_DE@euro’ denotes the locale that uses the Euro currency, in contrast to the older locale ‘de_DE’ which implies the use of the currency before 2002. It can also denote a dialect of the language, or the script used to write text (for example, ‘sr_RS@latin’ uses the Latin script, whereas ‘sr_RS’ uses the Cyrillic script to write Serbian), or the orthography rules, or similar.

On other systems, some variations of this scheme are used, such as ‘ll’. You can get the list of locales supported by your system for your language by running the command ‘locale -a | grep '^ll'’.

There are also two special locales:

• The locale called ‘C’.
  When it is used, it disables all localization: in this locale, all programs standardized by POSIX use English messages and an unspecified character encoding (often US-ASCII, but sometimes also ISO-8859-1 or UTF-8, depending on the operating system).
• The locale called ‘C.UTF-8’.
  This locale exists on all modern GNU and Unix systems, but not on all operating systems. When it is used, it disables all localization as well. It uses UTF-8 as character encoding.

2.3.2 Locale Environment Variables

A locale is composed of several locale categories, see Aspects in Native Language Support. When a program looks up locale dependent values, it does this according to the following environment variables, in priority order:

1. LANGUAGE
2. LC_ALL
3. LC_xxx, according to selected locale category: LC_CTYPE, LC_NUMERIC, LC_TIME, LC_COLLATE, LC_MONETARY, LC_MESSAGES, ...
4. LANG

Variables whose value is set but is empty are ignored in this lookup.

LANG is the normal environment variable for specifying a locale. As a user, you normally set this variable (unless some of the other variables have already been set by the system, in /etc/profile or similar initialization files).

LC_CTYPE, LC_NUMERIC, LC_TIME, LC_COLLATE, LC_MONETARY, LC_MESSAGES, and so on, are the environment variables meant to override LANG and affecting a single locale category only. For example, assume you are a Swedish user in Spain, and you want your programs to handle numbers and dates according to Spanish conventions, and only the messages should be in Swedish. Then you could create a locale named ‘sv_ES’ or ‘sv_ES.UTF-8’ by use of the localedef program. But it is simpler, and achieves the same effect, to set the LANG variable to es_ES.UTF-8 and the LC_MESSAGES variable to sv_SE.UTF-8; these two locales come already preinstalled with the operating system.

LC_ALL is an environment variable that overrides all of these. It is typically used in scripts that run particular programs. For example, configure scripts generated by GNU autoconf use LC_ALL to make sure that the configuration tests don’t operate in locale dependent ways.

Some systems, unfortunately, set LC_ALL in /etc/profile or in similar initialization files. As a user, you therefore have to unset this variable if you want to set LANG and optionally some of the other LC_xxx variables.

The LANGUAGE variable is described in the next subsection.

2.3.3 Specifying a Priority List of Languages

Not all programs have translations for all languages. By default, an English message is shown in place of a nonexistent translation. If you understand other languages, you can set up a priority list of languages. This is done through a different environment variable, called LANGUAGE. GNU gettext gives preference to LANGUAGE over LC_ALL and LANG for the purpose of message handling, but you still need to have LANG (or LC_ALL) set to the primary language; this is required by other parts of the system libraries. For example, some Swedish users who would rather read translations in German than English for when Swedish is not available, set LANGUAGE to ‘sv:de’ while leaving LANG to ‘sv_SE’.

Special advice for Norwegian users: The language code for Norwegian bokmål changed from ‘no’ to ‘nb’ recently (in 2003). During the transition period, while some message catalogs for this language are installed under ‘nb’ and some older ones under ‘no’, it is recommended for Norwegian users to set LANGUAGE to ‘nb:no’ so that both newer and older translations are used.

In the LANGUAGE environment variable, but not in the other environment variables, ‘ll_CC’ combinations can be abbreviated as ‘ll’ to denote the language’s main dialect. For example, ‘de’ is equivalent to ‘de_DE’ (German as spoken in Germany), and ‘pt’ to ‘pt_PT’ (Portuguese as spoken in Portugal) in this context.

Special advice for Chinese users: Users who want to see translations with Simplified Chinese characters should set LANGUAGE to zh_CN, whereas users who want to see translations with Traditional Chinese characters should set LANGUAGE to zh_TW. Chinese users in Singapore will want to set it to zh_SG:zh_CN, Chinese users in Hong Kong will want to set it to zh_HK:zh_TW, and Chinese users in Macao will want to set it to zh_MO:zh_TW. Here zh_CN or zh_TW, respectively, acts as fallback, since only few packages have translations for zh_SG, zh_HK, or zh_MO.

Note: The variable LANGUAGE is ignored if the locale is set to ‘C’. In other words, you have to first enable localization, by setting LANG (or LC_ALL) to a value other than ‘C’, before you can use a language priority list through the LANGUAGE variable.

4.3.1 Decent English style

Translatable strings should be in good English style. If slang language with abbreviations and shortcuts is used, often translators will not understand the message and will produce very inappropriate translations.

"%s: is parameter\n"

This is nearly untranslatable: Is the displayed item a parameter or the parameter?

"No match"

The ambiguity in this message makes it unintelligible: Is the program attempting to set something on fire? Does it mean "The given object does not match the template"? Does it mean "The template does not fit for any of the objects"?

In both cases, adding more words to the message will help both the translator and the English speaking user.

4.3.2 Entire sentences

Translatable strings should be entire sentences. It is often not possible to translate single verbs or adjectives in a substitutable way.

printf ("File %s is %s protected", filename, rw ? "write" : "read");

Most translators will not look at the source and will thus only see the string "File %s is %s protected", which is unintelligible. Change this to

printf (rw ? "File %s is write protected" : "File %s is read protected",
        filename);

This way the translator will not only understand the message, she will also be able to find the appropriate grammatical construction. A French translator for example translates "write protected" like "protected against writing".

Entire sentences are also important because in many languages, the declination of some word in a sentence depends on the gender or the number (singular/plural) of another part of the sentence. There are usually more interdependencies between words than in English. The consequence is that asking a translator to translate two half-sentences and then combining these two half-sentences through dumb string concatenation will not work, for many languages, even though it would work for English. That’s why translators need to handle entire sentences.

Often sentences don’t fit into a single line. If a sentence is output using two subsequent printf statements, like this

printf ("Locale charset \"%s\" is different from\n", lcharset);
printf ("input file charset \"%s\".\n", fcharset);

the translator would have to translate two half sentences, but nothing in the POT file would tell her that the two half sentences belong together. It is necessary to merge the two printf statements so that the translator can handle the entire sentence at once and decide at which place to insert a line break in the translation (if at all):

printf ("Locale charset \"%s\" is different from\n\
input file charset \"%s\".\n", lcharset, fcharset);

You may now ask: how about two or more adjacent sentences? Like in this case:

puts ("Apollo 13 scenario: Stack overflow handling failed.");
puts ("On the next stack overflow we will crash!!!");

Should these two statements merged into a single one? I would recommend to merge them if the two sentences are related to each other, because then it makes it easier for the translator to understand and translate both. On the other hand, if one of the two messages is a stereotypic one, occurring in other places as well, you will do a favour to the translator by not merging the two. (Identical messages occurring in several places are combined by xgettext, so the translator has to handle them once only.)

4.3.3 Split at paragraphs

Translatable strings should be limited to one paragraph; don’t let a single message be longer than ten lines. The reason is that when the translatable string changes, the translator is faced with the task of updating the entire translated string. Maybe only a single word will have changed in the English string, but the translator doesn’t see that (with the current translation tools), therefore she has to proofread the entire message.

Many GNU programs have a ‘--help’ output that extends over several screen pages. It is a courtesy towards the translators to split such a message into several ones of five to ten lines each. While doing that, you can also attempt to split the documented options into groups, such as the input options, the output options, and the informative output options. This will help every user to find the option he is looking for.

4.3.4 No string concatenation

Hardcoded string concatenation is sometimes used to construct English strings:

strcpy (s, "Replace ");
strcat (s, object1);
strcat (s, " with ");
strcat (s, object2);
strcat (s, "?");

In order to present to the translator only entire sentences, and also because in some languages the translator might want to swap the order of object1 and object2, it is necessary to change this to use a format string:

sprintf (s, "Replace %s with %s?", object1, object2);

String concatenation operator

In many programming languages, a particular operator denotes string concatenation at runtime (or possibly at compile time, if the compiler supports that).

• In C++, string concatenation of std::string objects is denoted by the ‘+’ operator.
• In Shell, string concatenation is denoted by mere juxtaposition of strings.
• In Python, string concatenation is denoted by the ‘+’ operator.
• In Smalltalk, string concatenation is denoted by the ‘,’ operator.
• In Java, string concatenation is denoted by the ‘+’ operator.
• In C#, string concatenation is denoted by the ‘+’ operator.
• In awk, string concatenation is denoted by mere juxtaposition of strings.
• In Perl, string concatenation is denoted by the ‘.’ operator.
• In PHP, string concatenation is denoted by the ‘.’ operator.
• In Ruby, string concatenation is denoted by the ‘+’ operator.
• In Lua, string concatenation is denoted by the ‘..’ operator.
• In JavaScript, string concatenation is denoted by the ‘+’ operator.
• In Vala, string concatenation is denoted by the ‘+’ operator.

So, for example, in Java, you would change

System.out.println("Replace "+object1+" with "+object2+"?");

into a statement involving a format string:

System.out.println(
    MessageFormat.format("Replace {0} with {1}?",
                         new Object[] { object1, object2 }));

Similarly, in C#, you would change

Console.WriteLine("Replace "+object1+" with "+object2+"?");

into a statement involving a format string:

Console.WriteLine(
    String.Format("Replace {0} with {1}?", object1, object2));

Strings with embedded expressions

In some programming languages, it is possible to have strings with embedded expressions. The expressions can refer to variables of the program. The value of such an expression is converted to a string and inserted in place of the expression; but no formatting function is called.

• In Shell language, double-quoted strings can contain references to variables, along with default values and string operations. Such as "Hello, $name!" or "Hello, ${name}!".
• In Python, f-strings can contain expressions. Such as f"Hello, {name}!".
• In C#, since C# 6.0, interpolated strings can contain expressions. Such as $"Hello, {name}!".
• In Tcl, strings are subject to variable substitution. Such as "Hello, $name!".
• In Perl, interpolated strings can contain expressions. Such as "Hello, $name!".
• In PHP, string literals are subject to variable parsing. Such as "Hello, $name!".
• In Ruby, interpolated strings can contain expressions. Such as "Hello, #{name}!".
• In JavaScript, since ES6, template literals can contain expressions. Such as `Hello, ${name}!`.

These cases are effectively string concatenation as well, just with a different syntax.

So, for example, in Python, you would change

print (f'Replace {object1.name} with {object2.name}?')

into a statement involving a format string:

print ('Replace %(name1)s with %(name2)s?'
       % { 'name1': object1.name, 'name2': object2.name })

or equivalently

print ('Replace {name1} with {name2}?'
       .format(name1 = object1.name, name2 = object2.name))

And in JavaScript, you would change

print (`Replace ${object1.name} with ${object2.name}?`)

into a statement involving a format string:

print ('Replace %s with %s?'.format(object1.name, object2.name))

Specifically in JavaScript, an alternative is to use a tagged template literal:

print (tag`Replace ${object1.name} with ${object2.name}?`)

and pass an option ‘--tag=tag:format’ to xgettext.

Format strings with embedded named references

Format strings with embedded named references are different: They are suitable for internationalization, because it is possible to insert a call to the gettext function (that will return a translated format string) before the argument values are inserted in place of the placeholders.

The format string types that allow embedded named references are:

• Shell format strings.
• In Python, those Python format strings that take a dictionary as argument, and the Python brace format strings.
• In Ruby, those Ruby format strings that take a hash table as argument.
• In Perl, the Perl brace format strings.

The <inttypes.h> macros

A similar case is compile time concatenation of strings. The ISO C 99 include file <inttypes.h> contains a macro PRId64 that can be used as a formatting directive for outputting an ‘int64_t’ integer through printf. It expands to a constant string, usually "d" or "ld" or "lld" or something like this, depending on the platform. Assume you have code like

printf ("The amount is %0" PRId64 "\n", number);

The gettext tools and library have special support for these <inttypes.h> macros. You can therefore simply write

printf (gettext ("The amount is %0" PRId64 "\n"), number);

The PO file will contain the string "The amount is %0<PRId64>\n". The translators will provide a translation containing "%0<PRId64>" as well, and at runtime the gettext function’s result will contain the appropriate constant string, "d" or "ld" or "lld".

This works only for the predefined <inttypes.h> macros. If you have defined your own similar macros, let’s say ‘MYPRId64’, that are not known to xgettext, the solution for this problem is to change the code like this:

char buf1[100];
sprintf (buf1, "%0" MYPRId64, number);
printf (gettext ("The amount is %s\n"), buf1);

This means, you put the platform dependent code in one statement, and the internationalization code in a different statement. Note that a buffer length of 100 is safe, because all available hardware integer types are limited to 128 bits, and to print a 128 bit integer one needs at most 54 characters, regardless whether in decimal, octal or hexadecimal.

4.3.5 No embedded URLs

It is good to not embed URLs in translatable strings, for several reasons:

• It avoids possible mistakes during copy and paste.
• Translators cannot translate the URLs or, by mistake, use the URLs from other packages that are present in their compendium.
• When the URLs change, translators don’t need to revisit the translation of the string.

The same holds for email addresses.

So, you would change

fputs (_("GNU GPL version 3 <https://gnu.org/licenses/gpl.html>\n"),
       stream);

to

fprintf (stream, _("GNU GPL version 3 <%s>\n"),
         "https://gnu.org/licenses/gpl.html");

4.3.6 No programmer-defined format string directives

The GNU C Library’s <printf.h> facility and the C++ standard library’s <format> header file make it possible for the programmer to define their own format string directives. However, such format directives cannot be used in translatable strings, for two reasons:

• There is no reference documentation for format strings with such directives, that the translators could consult. They would therefore have to guess where the directive starts and where it ends.
• An ‘msgfmt -c’ invocation cannot check whether the translator has produced a compatible translation of the format string. As a consequence, when a format string contains a programmer-defined directive, the program may crash at runtime when it uses the translated format string.

To avoid this situation, you need to move the formatting with the custom directive into a format string that does not get translated.

For example, assuming code that makes use of a %r directive:

fprintf (stream, _("The contents is: %r"), data);

you would rewrite it to:

char *tmp;
if (asprintf (&tmp, "%r", data) < 0)
  error (...);
fprintf (stream, _("The contents is: %s"), tmp);
free (tmp);

Similarly, in C++, assuming you have defined a custom formatter for the type of data, the code

cout << format (_("The contents is: {:#$#}"), data);

should be rewritten to:

string tmp = format ("{:#$#}", data);
cout << format (_("The contents is: {}"), tmp);

4.3.7 No unusual markup

Unusual markup or control characters should not be used in translatable strings. Translators will likely not understand the particular meaning of the markup or control characters.

For example, if you have a convention that ‘|’ delimits the left-hand and right-hand part of some GUI elements, translators will often not understand it without specific comments. It might be better to have the translator translate the left-hand and right-hand part separately.

Another example is the ‘argp’ convention to use a single ‘\v’ (vertical tab) control character to delimit two sections inside a string. This is flawed. Some translators may convert it to a simple newline, some to blank lines. With some PO file editors it may not be easy to even enter a vertical tab control character. So, you cannot be sure that the translation will contain a ‘\v’ character, at the corresponding position. The solution is, again, to let the translator translate two separate strings and combine at run-time the two translated strings with the ‘\v’ required by the convention.

HTML markup, however, is common enough that it’s probably ok to use in translatable strings. But please bear in mind that the GNU gettext tools don’t verify that the translations are well-formed HTML.

5.1.1 Input file location

‘inputfile …’

Input files.

‘-f file’ ¶

‘--files-from=file’

Read the names of the input files from file instead of getting them from the command line.

‘-D directory’ ¶

‘--directory=directory’

Add directory to the list of directories. Source files are searched relative to this list of directories. The resulting .po file will be written relative to the current directory, though.

If inputfile is ‘-’, standard input is read.

5.1.2 Output file location

‘-d name’ ¶

‘--default-domain=name’

Use name.po for output (instead of messages.po).

‘-o file’ ¶

‘--output=file’

Write output to specified file (instead of name.po or messages.po).

‘-p dir’ ¶

‘--output-dir=dir’

Output files will be placed in directory dir.

If the output file is ‘-’ or ‘/dev/stdout’, the output is written to standard output.

5.1.3 Choice of input file language

‘-L name’ ¶

‘--language=name’

Specifies the language of the input files. The supported languages are C, C++, ObjectiveC, PO, Shell, Python, Lisp, EmacsLisp, librep, Scheme, Guile, Smalltalk, Java, JavaProperties, C#, awk, YCP, Tcl, Perl, PHP, Ruby, GCC-source, NXStringTable, RST, RSJ, Glade, Lua, JavaScript, Vala, GSettings, Desktop.

‘-C’ ¶

‘--c++’

This is a shorthand for --language=C++.

By default the language is guessed depending on the input file name extension.

5.1.4 Input file interpretation

‘--from-code=name’ ¶

Specifies the encoding of the input files. This option is needed only if some untranslated message strings or their corresponding comments contain non-ASCII characters. Note that Tcl and Glade input files are always assumed to be in UTF-8, regardless of this option.

By default the input files are assumed to be in ASCII.

5.1.5 Operation mode

‘-j’ ¶

‘--join-existing’

Join messages with existing file.

‘-x file’ ¶

‘--exclude-file=file’

Entries from file are not extracted. file should be a PO or POT file.

‘-c[tag]’ ¶

‘--add-comments[=tag]’

Place comment blocks starting with tag and preceding keyword lines in the output file. Without a tag, the option means to put all comment blocks preceding keyword lines in the output file.

Note that comment blocks are only extracted if there is no program code between the comment and the string that gets extracted. For example, in the following C source code:

/* This is the first comment.  */
gettext ("foo");

/* This is the second comment: not extracted  */
gettext (
  "bar");

gettext (
  /* This is the third comment.  */
  "baz");

/* This is the fourth comment.  */

gettext ("I love blank lines in my programs");

the second comment line will not be extracted, because there is a line with some tokens between the comment line and the line that contains the string. But the fourth comment is extracted, because between it and the line with the string there is merely a blank line.

‘--check[=CHECK]’ ¶

Perform a syntax check on msgid and msgid_plural. The supported checks are:

‘ellipsis-unicode’

Prefer Unicode ellipsis character over ASCII ...

‘space-ellipsis’

Prohibit whitespace before an ellipsis character

‘quote-unicode’

Prefer Unicode quotation marks over ASCII "'`

‘bullet-unicode’

Prefer Unicode bullet character over ASCII * or -

The option has an effect on all input files. To enable or disable checks for a certain string, you can mark it with an xgettext: special comment in the source file. For example, if you specify the --check=space-ellipsis option, but want to suppress the check on a particular string, add the following comment:

/* xgettext: no-space-ellipsis-check */
gettext ("We really want a space before ellipsis here ...");

The xgettext: comment can be followed by flags separated with a comma. The possible flags are of the form ‘[no-]name-check’, where name is the name of a valid syntax check. If a flag is prefixed by no-, the meaning is negated.

Some tests apply the checks to each sentence within the msgid, rather than the whole string. xgettext detects the end of sentence by performing a pattern match, which usually looks for a period followed by a certain number of spaces. The number is specified with the --sentence-end option.

‘--sentence-end[=TYPE]’ ¶

The supported values are:

‘single-space’

Expect at least one whitespace after a period

‘double-space’

Expect at least two whitespaces after a period

5.1.6 Language specific options

‘-a’ ¶

‘--extract-all’

Extract all strings.

This option has an effect with most languages, namely C, C++, ObjectiveC, Shell, Python, Lisp, EmacsLisp, librep, Java, C#, awk, Tcl, Perl, PHP, GCC-source, Glade, Lua, JavaScript, Vala, GSettings.

‘-k[keywordspec]’ ¶

‘--keyword[=keywordspec]’

Specify keywordspec as an additional keyword to be looked for. Without a keywordspec, the option means to not use default keywords.

If keywordspec is a C identifier id, xgettext looks for strings in the first argument of each call to the function or macro id. If keywordspec is of the form ‘id:argnum’, xgettext looks for strings in the argnumth argument of the call. If keywordspec is of the form ‘id:argnum1,argnum2’, xgettext looks for strings in the argnum1st argument and in the argnum2nd argument of the call, and treats them as singular/plural variants for a message with plural handling. Also, if keywordspec is of the form ‘id:contextargnumc,argnum’ or ‘id:argnum,contextargnumc’, xgettext treats strings in the contextargnumth argument as a context specifier. And, as a special-purpose support for GNOME, if keywordspec is of the form ‘id:argnumg’, xgettext recognizes the argnumth argument as a string with context, using the GNOME glib syntax ‘"msgctxt|msgid"’.
Furthermore, if keywordspec is of the form ‘id:…,totalnumargst’, xgettext recognizes this argument specification only if the number of actual arguments is equal to totalnumargs. This is useful for disambiguating overloaded function calls in C++.
Finally, if keywordspec is of the form ‘id:argnum...,"xcomment"’, xgettext, when extracting a message from the specified argument strings, adds an extracted comment xcomment to the message. Note that when used through a normal shell command line, the double-quotes around the xcomment need to be escaped.

This option has an effect with most languages, namely C, C++, ObjectiveC, Shell, Python, Lisp, EmacsLisp, librep, Java, C#, awk, Tcl, Perl, PHP, GCC-source, Glade, Lua, JavaScript, Vala, GSettings, Desktop.

The default keyword specifications, which are always looked for if not explicitly disabled, are language dependent. They are:

• For C, C++, and GCC-source: gettext, dgettext:2, dcgettext:2, ngettext:1,2, dngettext:2,3, dcngettext:2,3, gettext_noop, and pgettext:1c,2, dpgettext:2c,3, dcpgettext:2c,3, npgettext:1c,2,3, dnpgettext:2c,3,4, dcnpgettext:2c,3,4.
• For Objective C: Like for C, and also NSLocalizedString, _, NSLocalizedStaticString, __.
• For Shell scripts: gettext, ngettext:1,2, eval_gettext, eval_ngettext:1,2, eval_pgettext:1c,2, eval_npgettext:1c,2,3.
• For Python: gettext, ugettext, dgettext:2, ngettext:1,2, ungettext:1,2, dngettext:2,3, _.
• For Lisp: gettext, ngettext:1,2, gettext-noop.
• For EmacsLisp: _.
• For librep: _.
• For Scheme and Guile: gettext, ngettext:1,2, gettext-noop.
• For Java: GettextResource.gettext:2, GettextResource.ngettext:2,3, GettextResource.pgettext:2c,3, GettextResource.npgettext:2c,3,4, gettext, ngettext:1,2, pgettext:1c,2, npgettext:1c,2,3, getString.
• For C#: GetString, GetPluralString:1,2, GetParticularString:1c,2, GetParticularPluralString:1c,2,3.
• For awk: dcgettext, dcngettext:1,2.
• For Tcl: ::msgcat::mc.
• For Perl: gettext, %gettext, $gettext, dgettext:2, dcgettext:2, ngettext:1,2, dngettext:2,3, dcngettext:2,3, gettext_noop.
• For PHP: _, gettext, dgettext:2, dcgettext:2, ngettext:1,2, dngettext:2,3, dcngettext:2,3.
• For Glade 1: label, title, text, format, copyright, comments, preview_text, tooltip.
• For Lua: _, gettext.gettext, gettext.dgettext:2, gettext.dcgettext:2, gettext.ngettext:1,2, gettext.dngettext:2,3, gettext.dcngettext:2,3.
• For JavaScript: _, gettext, dgettext:2, dcgettext:2, ngettext:1,2, dngettext:2,3, pgettext:1c,2, dpgettext:2c,3.
• For Vala: _, Q_, N_, NC_, dgettext:2, dcgettext:2, ngettext:1,2, dngettext:2,3, dpgettext:2c,3, dpgettext2:2c,3.
• For Desktop: Name, GenericName, Comment, Keywords.

To disable the default keyword specifications, the option ‘-k’ or ‘--keyword’ or ‘--keyword=’, without a keywordspec, can be used.

‘--flag=word:arg:flag’ ¶

Specifies additional flags for strings occurring as part of the argth argument of the function word. The possible flags are the possible format string indicators, such as ‘c-format’, and their negations, such as ‘no-c-format’, possibly prefixed with ‘pass-’.
The meaning of --flag=function:arg:lang-format is that in language lang, the specified function expects as argth argument a format string. (For those of you familiar with GCC function attributes, --flag=function:arg:c-format is roughly equivalent to the declaration ‘__attribute__ ((__format__ (__printf__, arg, ...)))’ attached to function in a C source file.) For example, if you use the ‘error’ function from GNU libc, you can specify its behaviour through --flag=error:3:c-format. The effect of this specification is that xgettext will mark as format strings all gettext invocations that occur as argth argument of function. This is useful when such strings contain no format string directives: together with the checks done by ‘msgfmt -c’ it will ensure that translators cannot accidentally use format string directives that would lead to a crash at runtime.
The meaning of --flag=function:arg:pass-lang-format is that in language lang, if the function call occurs in a position that must yield a format string, then its argth argument must yield a format string of the same type as well. (If you know GCC function attributes, the --flag=function:arg:pass-c-format option is roughly equivalent to the declaration ‘__attribute__ ((__format_arg__ (arg)))’ attached to function in a C source file.) For example, if you use the ‘_’ shortcut for the gettext function, you should use --flag=_:1:pass-c-format. The effect of this specification is that xgettext will propagate a format string requirement for a _("string") call to its first argument, the literal "string", and thus mark it as a format string. This is useful when such strings contain no format string directives: together with the checks done by ‘msgfmt -c’ it will ensure that translators cannot accidentally use format string directives that would lead to a crash at runtime.
This option has an effect with most languages, namely C, C++, ObjectiveC, Shell, Python, Lisp, EmacsLisp, librep, Scheme, Guile, Java, C#, awk, YCP, Tcl, Perl, PHP, GCC-source, Lua, JavaScript, Vala.

‘--tag=word:format’ ¶

Defines the behaviour of tagged template literals with tag word. This option has an effect only with language JavaScript.
format is a symbolic description of the first step of the JavaScript function named word, namely how this function constructs a format string based on the parts of the template literal. Currently only one value is supported: javascript-gnome-format, which describes the construction of a format string with numbered placeholders {0}, {1}, {2}, etc. For example, javascript-gnome-format transforms the template literal word`My name is ${id.name} and I am ${id.age} years old.` into the format string "My name is {0} and I am {1} years old.".

‘-T’ ¶

‘--trigraphs’

Understand ANSI C trigraphs for input (deprecated, since trigraphs have been removed from ISO C 23).
This option has an effect only with the languages C, C++, ObjectiveC.

‘--qt’ ¶

Recognize Qt format strings.
This option has an effect only with the language C++.

‘--kde’ ¶

Recognize KDE 4 format strings.
This option has an effect only with the language C++.

‘--boost’ ¶

Recognize Boost format strings.
This option has an effect only with the language C++.

‘--debug’ ¶

Use the flags c-format and possible-c-format to show who was responsible for marking a message as a format string. The latter form is used if the xgettext program decided, the former form is used if the programmer prescribed it.

By default only the c-format form is used. The translator should not have to care about these details.

This implementation of xgettext is able to process a few awkward cases, like strings in preprocessor macros, ANSI concatenation of adjacent strings, and escaped end of lines for continued strings.

5.1.7 Options for XML input files

When some of the input files are XML files and they are not of one of the types covered by the system-wide installed *.its files, a *.its file is needed for each such file type, so that xgettext can handle them. There are two ways to specify such a file:

• ‘--its=file’ ¶

  Use the ITS rules defined in file.

• The environment variable GETTEXTDATADIRS. Together with the *.its file, you need a corresponding *.loc file (see Preparing Rules for XML Internationalization). Furthermore you need to store these files in a directory parent_dir/its/ and set the environment variable GETTEXTDATADIRS to include parent_dir. More generally, the value of GETTEXTDATADIRS should be a colon-separated list of directory names.

Note that when the option --its is specified, the system-wide installed *.its files are ignored and the environment variable GETTEXTDATADIRS has no effect either.

5.1.8 Output details

‘--color’ ¶

‘--color=when’

Specify whether or when to use colors and other text attributes. See The --color option for details.

‘--style=style_file’ ¶

Specify the CSS style rule file to use for --color. See The --style option for details.

‘--force-po’ ¶

Always write an output file even if no message is defined.

‘-i’ ¶

‘--indent’

Write the .po file using indented style.

‘--no-location’ ¶

Do not write ‘#: filename:line’ lines. Note that using this option makes it harder for technically skilled translators to understand each message’s context.

‘-n’ ¶

‘--add-location=type’

Generate ‘#: filename:line’ lines (default).

The optional type can be either ‘full’, ‘file’, or ‘never’. If it is not given or ‘full’, it generates the lines with both file name and line number. If it is ‘file’, the line number part is omitted. If it is ‘never’, it completely suppresses the lines (same as --no-location).

‘--strict’ ¶

Write out a strict Uniforum conforming PO file. Note that this Uniforum format should be avoided because it doesn’t support the GNU extensions.

‘--properties-output’ ¶

Write out a Java ResourceBundle in Java .properties syntax. Note that this file format doesn’t support plural forms and silently drops obsolete messages.

‘--stringtable-output’ ¶

Write out a NeXTstep/GNUstep localized resource file in .strings syntax. Note that this file format doesn’t support plural forms.

‘--itstool’ ¶

Write out comments recognized by itstool (http://itstool.org). Note that this is only effective with XML files.

‘-w number’ ¶

‘--width=number’

Set the output page width. Long strings in the output files will be split across multiple lines in order to ensure that each line’s width (= number of screen columns) is less or equal to the given number.

‘--no-wrap’ ¶

Do not break long message lines. Message lines whose width exceeds the output page width will not be split into several lines. Only file reference lines which are wider than the output page width will be split.

‘-s’ ¶

‘--sort-output’

Generate sorted output (deprecated). Note that using this option makes it much harder for the translator to understand each message’s context.

‘-F’ ¶

‘--sort-by-file’

Sort output by file location.

‘--omit-header’ ¶

Don’t write header with ‘msgid ""’ entry. Note: Using this option may lead to an error in subsequent operations if the output contains non-ASCII characters.

This is useful for testing purposes because it eliminates a source of variance for generated .gmo files. With --omit-header, two invocations of xgettext on the same files with the same options at different times are guaranteed to produce the same results.

Note that using this option will lead to an error if the resulting file would not entirely be in ASCII.

‘--copyright-holder=string’ ¶

Set the copyright holder in the output. string should be the copyright holder of the surrounding package. (Note that the msgstr strings, extracted from the package’s sources, belong to the copyright holder of the package.) Translators are expected to transfer or disclaim the copyright for their translations, so that package maintainers can distribute them without legal risk. If string is empty, the output files are marked as being in the public domain; in this case, the translators are expected to disclaim their copyright, again so that package maintainers can distribute them without legal risk.

The default value for string is the Free Software Foundation, Inc., simply because xgettext was first used in the GNU project.

‘--foreign-user’ ¶

Omit FSF copyright in output. This option is equivalent to ‘--copyright-holder=''’. It can be useful for packages outside the GNU project that want their translations to be in the public domain.

‘--package-name=package’ ¶

Set the package name in the header of the output.

‘--package-version=version’ ¶

Set the package version in the header of the output. This option has an effect only if the ‘--package-name’ option is also used.

‘--msgid-bugs-address=email@address’ ¶

Set the reporting address for msgid bugs. This is the email address or URL to which the translators shall report bugs in the untranslated strings:

• - Strings which are not entire sentences; see the maintainer guidelines in Preparing Translatable Strings.
• - Strings which use unclear terms or require additional context to be understood.
• - Strings which make invalid assumptions about notation of date, time or money.
• - Pluralisation problems.
• - Incorrect English spelling.
• - Incorrect formatting.

It can be your email address, or a mailing list address where translators can write to without being subscribed, or the URL of a web page through which the translators can contact you.

The default value is empty, which means that translators will be clueless! Don’t forget to specify this option.

‘-m[string]’ ¶

‘--msgstr-prefix[=string]’

Use string (or "" if not specified) as prefix for msgstr values.

‘-M[string]’ ¶

‘--msgstr-suffix[=string]’

Use string (or "" if not specified) as suffix for msgstr values.

5.1.9 Informative output

‘-h’ ¶

‘--help’

Display this help and exit.

‘-V’ ¶

‘--version’

Output version information and exit.

‘-v’ ¶

‘--verbose’

Increase verbosity level.

5.1.10 Example

A sample invocation of xgettext, in a project that has a single source file src/hello.c that uses ‘_’ as shorthand for the gettext function, could be:

xgettext -o hello.pot \
         --add-comments=TRANSLATORS: \
         --keyword=_ --flag=_:1:pass-c-format \
         --directory=.. \
         src/hello.c

6.1.1 Input file location

‘-i inputfile’ ¶

‘--input=inputfile’

Input POT file.

If no inputfile is given, the current directory is searched for the POT file. If it is ‘-’, standard input is read.

6.1.2 Output file location

‘-o file’ ¶

‘--output-file=file’

Write output to specified PO file.

If no output file is given, it depends on the ‘--locale’ option or the user’s locale setting. If it is ‘-’, the results are written to standard output.

6.1.3 Input file syntax

‘-P’ ¶

‘--properties-input’

Assume the input file is a Java ResourceBundle in Java .properties syntax, not in PO file syntax.

‘--stringtable-input’ ¶

Assume the input file is a NeXTstep/GNUstep localized resource file in .strings syntax, not in PO file syntax.

6.1.4 Output details

‘-l ll_CC[.encoding]’ ¶

‘--locale=ll_CC[.encoding]’

Set target locale. ll should be a language code, and CC should be a country code. The optional part .encoding specifies the encoding of the locale; most often this part is .UTF-8. The command ‘locale -a’ can be used to output a list of all installed locales. The default is the user’s locale setting.

‘--no-translator’ ¶

Declares that the PO file will not have a human translator and is instead automatically generated.

‘--color’ ¶

‘--color=when’

Specify whether or when to use colors and other text attributes. See The --color option for details.

‘--style=style_file’ ¶

Specify the CSS style rule file to use for --color. See The --style option for details.

‘-p’ ¶

‘--properties-output’

Write out a Java ResourceBundle in Java .properties syntax. Note that this file format doesn’t support plural forms and silently drops obsolete messages.

‘--stringtable-output’ ¶

Write out a NeXTstep/GNUstep localized resource file in .strings syntax. Note that this file format doesn’t support plural forms.

‘-w number’ ¶

‘--width=number’

Set the output page width. Long strings in the output files will be split across multiple lines in order to ensure that each line’s width (= number of screen columns) is less or equal to the given number.

‘--no-wrap’ ¶

Do not break long message lines. Message lines whose width exceeds the output page width will not be split into several lines. Only file reference lines which are wider than the output page width will be split.

6.1.5 Informative output

‘-h’ ¶

‘--help’

Display this help and exit.

‘-V’ ¶

‘--version’

Output version information and exit.

7.1.1 Input file location

‘def.po’

Translations referring to old sources.

‘ref.pot’

References to the new sources.

‘-D directory’ ¶

‘--directory=directory’

Add directory to the list of directories. Source files are searched relative to this list of directories. The resulting .po file will be written relative to the current directory, though.

‘-C file’ ¶

‘--compendium=file’

Specify an additional library of message translations. See Using Translation Compendia. This option may be specified more than once.

7.1.2 Operation mode

‘-U’ ¶

‘--update’

Update def.po. Do nothing if def.po is already up to date.

7.1.3 Output file location

‘-o file’ ¶

‘--output-file=file’

Write output to specified file.

The results are written to standard output if no output file is specified or if it is ‘-’.

7.1.4 Output file location in update mode

The result is written back to def.po.

‘--backup=control’ ¶

Make a backup of def.po

‘--suffix=suffix’ ¶

Override the usual backup suffix.

The version control method may be selected via the --backup option or through the VERSION_CONTROL environment variable. Here are the values:

‘none’

‘off’

Never make backups (even if --backup is given).

‘numbered’

‘t’

Make numbered backups.

‘existing’

‘nil’

Make numbered backups if numbered backups for this file already exist, otherwise make simple backups.

‘simple’

‘never’

Always make simple backups.

The backup suffix is ‘~’, unless set with --suffix or the SIMPLE_BACKUP_SUFFIX environment variable.

7.1.5 Operation modifiers

‘-m’ ¶

‘--multi-domain’

Apply ref.pot to each of the domains in def.po.

‘--for-msgfmt’ ¶

Produce a PO file meant for msgfmt only, not for a translator. This option omits untranslated messages, fuzzy messages (except the header entry), and obsolete messages from the output. Also, it omits translator comments and ‘#: filename:line’ lines from the output. In particular, this option implies ‘--no-fuzzy-matching’.

‘-N’ ¶

‘--no-fuzzy-matching’

Do not use fuzzy matching when an exact match is not found. This may speed up the operation considerably.

‘--previous’ ¶

Keep the previous msgids of translated messages, marked with ‘#|’, when adding the fuzzy marker to such messages.

7.1.6 Input file syntax

‘-P’ ¶

‘--properties-input’

Assume the input files are Java ResourceBundles in Java .properties syntax, not in PO file syntax.

‘--stringtable-input’ ¶

Assume the input files are NeXTstep/GNUstep localized resource files in .strings syntax, not in PO file syntax.

7.1.7 Output details

‘--lang=catalogname’ ¶

Specify the ‘Language’ field to be used in the header entry. See Filling in the Header Entry for the meaning of this field. Note: The ‘Language-Team’ and ‘Plural-Forms’ fields are left unchanged. If this option is not specified, the ‘Language’ field is inferred, as best as possible, from the ‘Language-Team’ field.

‘--color’ ¶

‘--color=when’

Specify whether or when to use colors and other text attributes. See The --color option for details.

‘--style=style_file’ ¶

Specify the CSS style rule file to use for --color. See The --style option for details.

‘--force-po’ ¶

Always write an output file even if it contains no message.

‘-i’ ¶

‘--indent’

Write the .po file using indented style.

‘--no-location’ ¶

Do not write ‘#: filename:line’ lines.

‘-n’ ¶

‘--add-location=type’

Generate ‘#: filename:line’ lines (default).

The optional type can be either ‘full’, ‘file’, or ‘never’. If it is not given or ‘full’, it generates the lines with both file name and line number. If it is ‘file’, the line number part is omitted. If it is ‘never’, it completely suppresses the lines (same as --no-location).

‘--strict’ ¶

Write out a strict Uniforum conforming PO file. Note that this Uniforum format should be avoided because it doesn’t support the GNU extensions.

‘-p’ ¶

‘--properties-output’

Write out a Java ResourceBundle in Java .properties syntax. Note that this file format doesn’t support plural forms and silently drops obsolete messages.

‘--stringtable-output’ ¶

Write out a NeXTstep/GNUstep localized resource file in .strings syntax. Note that this file format doesn’t support plural forms.

‘-w number’ ¶

‘--width=number’

Set the output page width. Long strings in the output files will be split across multiple lines in order to ensure that each line’s width (= number of screen columns) is less or equal to the given number.

‘--no-wrap’ ¶

Do not break long message lines. Message lines whose width exceeds the output page width will not be split into several lines. Only file reference lines which are wider than the output page width will be split.

‘-s’ ¶

‘--sort-output’

Generate sorted output (deprecated). Note that using this option makes it much harder for the translator to understand each message’s context.

‘-F’ ¶

‘--sort-by-file’

Sort output by file location.

7.1.8 Informative output

‘-h’ ¶

‘--help’

Display this help and exit.

‘-V’ ¶

‘--version’

Output version information and exit.

‘-v’ ¶

‘--verbose’

Increase verbosity level.

‘-q’ ¶

‘--quiet’

‘--silent’

Suppress progress indicators.

8.7.1 Completing GNU gettext Installation

Once you have received, unpacked, configured and compiled the GNU gettext distribution, the ‘make install’ command puts in place the programs xgettext, msgfmt, gettext, and msgmerge, as well as their available message catalogs. To top off a comfortable installation, you might also want to make the PO mode available to your Emacs users.

During the installation of the PO mode, you might want to modify your file .emacs, once and for all, so it contains a few lines looking like:

(setq auto-mode-alist
      (cons '("\\.po\\'\\|\\.po\\." . po-mode) auto-mode-alist))
(autoload 'po-mode "po-mode" "Major mode for translators to edit PO files" t)

Later, whenever you edit some .po file, or any file having the string ‘.po.’ within its name, Emacs loads po-mode.elc (or po-mode.el) as needed, and automatically activates PO mode commands for the associated buffer. The string PO appears in the mode line for any buffer for which PO mode is active. Many PO files may be active at once in a single Emacs session.

If you are using Emacs version 20 or newer, and have already installed the appropriate international fonts on your system, you may also tell Emacs how to determine automatically the coding system of every PO file. This will often (but not always) cause the necessary fonts to be loaded and used for displaying the translations on your Emacs screen. For this to happen, add the lines:

(modify-coding-system-alist 'file "\\.po\\'\\|\\.po\\."
                            'po-find-file-coding-system)
(autoload 'po-find-file-coding-system "po-mode")

to your .emacs file. If, with this, you still see boxes instead of international characters, try a different font set (via Shift Mouse button 1).

8.7.2 Main PO mode Commands

After setting up Emacs with something similar to the lines in Completing GNU gettext Installation, PO mode is activated for a window when Emacs finds a PO file in that window. This puts the window read-only and establishes a po-mode-map, which is a genuine Emacs mode, in a way that is not derived from text mode in any way. Functions found on po-mode-hook, if any, will be executed.

When PO mode is active in a window, the letters ‘PO’ appear in the mode line for that window. The mode line also displays how many entries of each kind are held in the PO file. For example, the string ‘132t+3f+10u+2o’ would tell the translator that the PO mode contains 132 translated entries (see Translated Entries, 3 fuzzy entries (see Fuzzy Entries), 10 untranslated entries (see Untranslated Entries) and 2 obsolete entries (see Obsolete Entries). Zero-coefficients items are not shown. So, in this example, if the fuzzy entries were unfuzzied, the untranslated entries were translated and the obsolete entries were deleted, the mode line would merely display ‘145t’ for the counters.

The main PO commands are those which do not fit into the other categories of subsequent sections. These allow for quitting PO mode or for managing windows in special ways.

_ ¶

Undo last modification to the PO file (po-undo).

Q ¶

Quit processing and save the PO file (po-quit).

q ¶

Quit processing, possibly after confirmation (po-confirm-and-quit).

0 ¶

Temporary leave the PO file window (po-other-window).

? ¶

h

Show help about PO mode (po-help).

= ¶

Give some PO file statistics (po-statistics).

V ¶

Batch validate the format of the whole PO file (po-validate).

The command _ (po-undo) interfaces to the Emacs undo facility. See Undoing Changes in The Emacs Editor. Each time _ is typed, modifications which the translator did to the PO file are undone a little more. For the purpose of undoing, each PO mode command is atomic. This is especially true for the RET command: the whole edition made by using a single use of this command is undone at once, even if the edition itself implied several actions. However, while in the editing window, one can undo the edition work quite parsimoniously.

The commands Q (po-quit) and q (po-confirm-and-quit) are used when the translator is done with the PO file. The former is a bit less verbose than the latter. If the file has been modified, it is saved to disk first. In both cases, and prior to all this, the commands check if any untranslated messages remain in the PO file and, if so, the translator is asked if she really wants to leave off working with this PO file. This is the preferred way of getting rid of an Emacs PO file buffer. Merely killing it through the usual command C-x k (kill-buffer) is not the tidiest way to proceed.

The command 0 (po-other-window) is another, softer way, to leave PO mode, temporarily. It just moves the cursor to some other Emacs window, and pops one if necessary. For example, if the translator just got PO mode to show some source context in some other, she might discover some apparent bug in the program source that needs correction. This command allows the translator to change sex, become a programmer, and have the cursor right into the window containing the program she (or rather he) wants to modify. By later getting the cursor back in the PO file window, or by asking Emacs to edit this file once again, PO mode is then recovered.

The command h (po-help) displays a summary of all available PO mode commands. The translator should then type any character to resume normal PO mode operations. The command ? has the same effect as h.

The command = (po-statistics) computes the total number of entries in the PO file, the ordinal of the current entry (counted from 1), the number of untranslated entries, the number of obsolete entries, and displays all these numbers.

The command V (po-validate) launches msgfmt in checking and verbose mode over the current PO file. This command first offers to save the current PO file on disk. The msgfmt tool, from GNU gettext, has the purpose of creating a MO file out of a PO file, and PO mode uses the features of this program for checking the overall format of a PO file, as well as all individual entries.

The program msgfmt runs asynchronously with Emacs, so the translator regains control immediately while her PO file is being studied. Error output is collected in the Emacs ‘*compilation*’ buffer, displayed in another window. The regular Emacs command C-x` (next-error), as well as other usual compile commands, allow the translator to reposition quickly to the offending parts of the PO file. Once the cursor is on the line in error, the translator may decide on any PO mode action which would help correcting the error.

8.7.3 Entry Positioning

The cursor in a PO file window is almost always part of an entry. The only exceptions are the special case when the cursor is after the last entry in the file, or when the PO file is empty. The entry where the cursor is found to be is said to be the current entry. Many PO mode commands operate on the current entry, so moving the cursor does more than allowing the translator to browse the PO file, this also selects on which entry commands operate.

Some PO mode commands alter the position of the cursor in a specialized way. A few of those special purpose positioning are described here, the others are described in following sections (for a complete list try C-h m):

. ¶

Redisplay the current entry (po-current-entry).

n ¶

Select the entry after the current one (po-next-entry).

p ¶

Select the entry before the current one (po-previous-entry).

< ¶

Select the first entry in the PO file (po-first-entry).

> ¶

Select the last entry in the PO file (po-last-entry).

m ¶

Record the location of the current entry for later use (po-push-location).

r ¶

Return to a previously saved entry location (po-pop-location).

x ¶

Exchange the current entry location with the previously saved one (po-exchange-location).

Any Emacs command able to reposition the cursor may be used to select the current entry in PO mode, including commands which move by characters, lines, paragraphs, screens or pages, and search commands. However, there is a kind of standard way to display the current entry in PO mode, which usual Emacs commands moving the cursor do not especially try to enforce. The command . (po-current-entry) has the sole purpose of redisplaying the current entry properly, after the current entry has been changed by means external to PO mode, or the Emacs screen otherwise altered.

It is yet to be decided if PO mode helps the translator, or otherwise irritates her, by forcing a rigid window disposition while she is doing her work. We originally had quite precise ideas about how windows should behave, but on the other hand, anyone used to Emacs is often happy to keep full control. Maybe a fixed window disposition might be offered as a PO mode option that the translator might activate or deactivate at will, so it could be offered on an experimental basis. If nobody feels a real need for using it, or a compulsion for writing it, we should drop this whole idea. The incentive for doing it should come from translators rather than programmers, as opinions from an experienced translator are surely more worth to me than opinions from programmers thinking about how others should do translation.

The commands n (po-next-entry) and p (po-previous-entry) move the cursor the entry following, or preceding, the current one. If n is given while the cursor is on the last entry of the PO file, or if p is given while the cursor is on the first entry, no move is done.

The commands < (po-first-entry) and > (po-last-entry) move the cursor to the first entry, or last entry, of the PO file. When the cursor is located past the last entry in a PO file, most PO mode commands will return an error saying ‘After last entry’. Moreover, the commands < and > have the special property of being able to work even when the cursor is not into some PO file entry, and one may use them for nicely correcting this situation. But even these commands will fail on a truly empty PO file. There are development plans for the PO mode for it to interactively fill an empty PO file from sources. See Marking Translatable Strings.

The translator may decide, before working at the translation of a particular entry, that she needs to browse the remainder of the PO file, maybe for finding the terminology or phraseology used in related entries. She can of course use the standard Emacs idioms for saving the current cursor location in some register, and use that register for getting back, or else, use the location ring.

PO mode offers another approach, by which cursor locations may be saved onto a special stack. The command m (po-push-location) merely adds the location of current entry to the stack, pushing the already saved locations under the new one. The command r (po-pop-location) consumes the top stack element and repositions the cursor to the entry associated with that top element. This position is then lost, for the next r will move the cursor to the previously saved location, and so on until no locations remain on the stack.

If the translator wants the position to be kept on the location stack, maybe for taking a look at the entry associated with the top element, then go elsewhere with the intent of getting back later, she ought to use m immediately after r.

The command x (po-exchange-location) simultaneously repositions the cursor to the entry associated with the top element of the stack of saved locations, and replaces that top element with the location of the current entry before the move. Consequently, repeating the x command toggles alternatively between two entries. For achieving this, the translator will position the cursor on the first entry, use m, then position to the second entry, and merely use x for making the switch.

8.7.4 Normalizing Strings in Entries

There are many different ways for encoding a particular string into a PO file entry, because there are so many different ways to split and quote multi-line strings, and even, to represent special characters by backslashed escaped sequences. Some features of PO mode rely on the ability for PO mode to scan an already existing PO file for a particular string encoded into the msgid field of some entry. Even if PO mode has internally all the built-in machinery for implementing this recognition easily, doing it fast is technically difficult. To facilitate a solution to this efficiency problem, we decided on a canonical representation for strings.

A conventional representation of strings in a PO file is currently under discussion, and PO mode experiments with a canonical representation. Having both xgettext and PO mode converging towards a uniform way of representing equivalent strings would be useful, as the internal normalization needed by PO mode could be automatically satisfied when using xgettext from GNU gettext. An explicit PO mode normalization should then be only necessary for PO files imported from elsewhere, or for when the convention itself evolves.

So, for achieving normalization of at least the strings of a given PO file needing a canonical representation, the following PO mode command is available:

M-x po-normalize ¶

Tidy the whole PO file by making entries more uniform.

The special command M-x po-normalize, which has no associated keys, revises all entries, ensuring that strings of both original and translated entries use uniform internal quoting in the PO file. It also removes any crumb after the last entry. This command may be useful for PO files freshly imported from elsewhere, or if we ever improve on the canonical quoting format we use. This canonical format is not only meant for getting cleaner PO files, but also for greatly speeding up msgid string lookup for some other PO mode commands.

M-x po-normalize presently makes three passes over the entries. The first implements heuristics for converting PO files for GNU gettext 0.6 and earlier, in which msgid and msgstr fields were using K&R style C string syntax for multi-line strings. These heuristics may fail for comments not related to obsolete entries and ending with a backslash; they also depend on subsequent passes for finalizing the proper commenting of continued lines for obsolete entries. This first pass might disappear once all oldish PO files would have been adjusted. The second and third pass normalize all msgid and msgstr strings respectively. They also clean out those trailing backslashes used by XView’s msgfmt for continued lines.

Having such an explicit normalizing command allows for importing PO files from other sources, but also eases the evolution of the current convention, evolution driven mostly by aesthetic concerns, as of now. It is easy to make suggested adjustments at a later time, as the normalizing command and eventually, other GNU gettext tools should greatly automate conformance. A description of the canonical string format is given below, for the particular benefit of those not having Emacs handy, and who would nevertheless want to handcraft their PO files in nice ways.

Right now, in PO mode, strings are single line or multi-line. A string goes multi-line if and only if it has embedded newlines, that is, if it matches ‘[^\n]\n+[^\n]’. So, we would have:

msgstr "\n\nHello, world!\n\n\n"

but, replacing the space by a newline, this becomes:

msgstr ""
"\n"
"\n"
"Hello,\n"
"world!\n"
"\n"
"\n"

We are deliberately using a caricatural example, here, to make the point clearer. Usually, multi-lines are not that bad looking. It is probable that we will implement the following suggestion. We might lump together all initial newlines into the empty string, and also all newlines introducing empty lines (that is, for n > 1, the n-1’th last newlines would go together on a separate string), so making the previous example appear:

msgstr "\n\n"
"Hello,\n"
"world!\n"
"\n\n"

There are a few yet undecided little points about string normalization, to be documented in this manual, once these questions settle.

8.7.5 Translated Entries

Each PO file entry for which the msgstr field has been filled with a translation, and which is not marked as fuzzy (see Fuzzy Entries), is said to be a translated entry. Only translated entries will later be compiled by GNU msgfmt and become usable in programs. Other entry types will be excluded; translation will not occur for them.

Some commands are more specifically related to translated entry processing.

t ¶

Find the next translated entry (po-next-translated-entry).

T ¶

Find the previous translated entry (po-previous-translated-entry).

The commands t (po-next-translated-entry) and T (po-previous-translated-entry) move forwards or backwards, chasing for an translated entry. If none is found, the search is extended and wraps around in the PO file buffer.

Translated entries usually result from the translator having edited in a translation for them, Modifying Translations. However, if the variable po-auto-fuzzy-on-edit is not nil, the entry having received a new translation first becomes a fuzzy entry, which ought to be later unfuzzied before becoming an official, genuine translated entry. See Fuzzy Entries.

8.7.6 Fuzzy Entries

Each PO file entry may have a set of attributes, which are qualities given a name and explicitly associated with the translation, using a special system comment. One of these attributes has the name fuzzy, and entries having this attribute are said to have a fuzzy translation. They are called fuzzy entries, for short.

Fuzzy entries, even if they account for translated entries for most other purposes, usually call for revision by the translator. Those may be produced by applying the program msgmerge to update an older translated PO files according to a new PO template file, when this tool hypothesises that some new msgid has been modified only slightly out of an older one, and chooses to pair what it thinks to be the old translation for the new modified entry. The slight alteration in the original string (the msgid string) should often be reflected in the translated string, and this requires the intervention of the translator. For this reason, msgmerge might mark some entries as being fuzzy.

Also, the translator may decide herself to mark an entry as fuzzy for her own convenience, when she wants to remember that the entry has to be later revisited. So, some commands are more specifically related to fuzzy entry processing.

f ¶

Find the next fuzzy entry (po-next-fuzzy-entry).

F ¶

Find the previous fuzzy entry (po-previous-fuzzy-entry).

TAB ¶

Remove the fuzzy attribute of the current entry (po-unfuzzy).

The commands f (po-next-fuzzy-entry) and F (po-previous-fuzzy-entry) move forwards or backwards, chasing for a fuzzy entry. If none is found, the search is extended and wraps around in the PO file buffer.

The command TAB (po-unfuzzy) removes the fuzzy attribute associated with an entry, usually leaving it translated. Further, if the variable po-auto-select-on-unfuzzy has not the nil value, the TAB command will automatically chase for another interesting entry to work on. The initial value of po-auto-select-on-unfuzzy is nil.

The initial value of po-auto-fuzzy-on-edit is nil. However, if the variable po-auto-fuzzy-on-edit is set to t, any entry edited through the RET command is marked fuzzy, as a way to ensure some kind of double check, later. In this case, the usual paradigm is that an entry becomes fuzzy (if not already) whenever the translator modifies it. If she is satisfied with the translation, she then uses TAB to pick another entry to work on, clearing the fuzzy attribute on the same blow. If she is not satisfied yet, she merely uses SPC to chase another entry, leaving the entry fuzzy.

The translator may also use the DEL command (po-fade-out-entry) over any translated entry to mark it as being fuzzy, when she wants to easily leave a trace she wants to later return working at this entry.

Also, when time comes to quit working on a PO file buffer with the q command, the translator is asked for confirmation, if fuzzy string still exists.

8.7.7 Untranslated Entries

When xgettext originally creates a PO file, unless told otherwise, it initializes the msgid field with the untranslated string, and leaves the msgstr string to be empty. Such entries, having an empty translation, are said to be untranslated entries. Later, when the programmer slightly modifies some string right in the program, this change is later reflected in the PO file by the appearance of a new untranslated entry for the modified string.

The usual commands moving from entry to entry consider untranslated entries on the same level as active entries. Untranslated entries are easily recognizable by the fact they end with ‘msgstr ""’.

The work of the translator might be (quite naively) seen as the process of seeking for an untranslated entry, editing a translation for it, and repeating these actions until no untranslated entries remain. Some commands are more specifically related to untranslated entry processing.

u ¶

Find the next untranslated entry (po-next-untranslated-entry).

U ¶

Find the previous untranslated entry (po-previous-untransted-entry).

k ¶

Turn the current entry into an untranslated one (po-kill-msgstr).

The commands u (po-next-untranslated-entry) and U (po-previous-untransted-entry) move forwards or backwards, chasing for an untranslated entry. If none is found, the search is extended and wraps around in the PO file buffer.

An entry can be turned back into an untranslated entry by merely emptying its translation, using the command k (po-kill-msgstr). See Modifying Translations.

Also, when time comes to quit working on a PO file buffer with the q command, the translator is asked for confirmation, if some untranslated string still exists.

8.7.8 Obsolete Entries

By obsolete PO file entries, we mean those entries which are commented out, usually by msgmerge when it found that the translation is not needed anymore by the package being localized.

The usual commands moving from entry to entry consider obsolete entries on the same level as active entries. Obsolete entries are easily recognizable by the fact that all their lines start with #, even those lines containing msgid or msgstr.

Commands exist for emptying the translation or reinitializing it to the original untranslated string. Commands interfacing with the kill ring may force some previously saved text into the translation. The user may interactively edit the translation. All these commands may apply to obsolete entries, carefully leaving the entry obsolete after the fact.

Moreover, some commands are more specifically related to obsolete entry processing.

o ¶

Find the next obsolete entry (po-next-obsolete-entry).

O ¶

Find the previous obsolete entry (po-previous-obsolete-entry).

DEL ¶

Make an active entry obsolete, or zap out an obsolete entry (po-fade-out-entry).

The commands o (po-next-obsolete-entry) and O (po-previous-obsolete-entry) move forwards or backwards, chasing for an obsolete entry. If none is found, the search is extended and wraps around in the PO file buffer.

PO mode does not provide ways for un-commenting an obsolete entry and making it active, because this would reintroduce an original untranslated string which does not correspond to any marked string in the program sources. This goes with the philosophy of never introducing useless msgid values.

However, it is possible to comment out an active entry, so making it obsolete. GNU gettext utilities will later react to the disappearance of a translation by using the untranslated string. The command DEL (po-fade-out-entry) pushes the current entry a little further towards annihilation. If the entry is active (it is a translated entry), then it is first made fuzzy. If it is already fuzzy, then the entry is merely commented out, with confirmation. If the entry is already obsolete, then it is completely deleted from the PO file. It is easy to recycle the translation so deleted into some other PO file entry, usually one which is untranslated. See Modifying Translations.

Here is a quite interesting problem to solve for later development of PO mode, for those nights you are not sleepy. The idea would be that PO mode might become bright enough, one of these days, to make good guesses at retrieving the most probable candidate, among all obsolete entries, for initializing the translation of a newly appeared string. I think it might be a quite hard problem to do this algorithmically, as we have to develop good and efficient measures of string similarity. Right now, PO mode completely lets the decision to the translator, when the time comes to find the adequate obsolete translation, it merely tries to provide handy tools for helping her to do so.

8.7.9 Modifying Translations

PO mode prevents direct modification of the PO file, by the usual means Emacs gives for altering a buffer’s contents. By doing so, it pretends helping the translator to avoid little clerical errors about the overall file format, or the proper quoting of strings, as those errors would be easily made. Other kinds of errors are still possible, but some may be caught and diagnosed by the batch validation process, which the translator may always trigger by the V command. For all other errors, the translator has to rely on her own judgment, and also on the linguistic reports submitted to her by the users of the translated package, having the same mother tongue.

When the time comes to create a translation, correct an error diagnosed mechanically or reported by a user, the translators have to resort to using the following commands for modifying the translations.

RET ¶

Interactively edit the translation (po-edit-msgstr).

LFD ¶

C-j

Reinitialize the translation with the original, untranslated string (po-msgid-to-msgstr).

k ¶

Save the translation on the kill ring, and delete it (po-kill-msgstr).

w ¶

Save the translation on the kill ring, without deleting it (po-kill-ring-save-msgstr).

y ¶

Replace the translation, taking the new from the kill ring (po-yank-msgstr).

The command RET (po-edit-msgstr) opens a new Emacs window meant to edit in a new translation, or to modify an already existing translation. The new window contains a copy of the translation taken from the current PO file entry, all ready for edition, expunged of all quoting marks, fully modifiable and with the complete extent of Emacs modifying commands. When the translator is done with her modifications, she may use C-c C-c to close the subedit window with the automatically requoted results, or C-c C-k to abort her modifications. See Details of Sub Edition, for more information.

The command LFD (po-msgid-to-msgstr) initializes, or reinitializes the translation with the original string. This command is normally used when the translator wants to redo a fresh translation of the original string, disregarding any previous work.

It is possible to arrange so, whenever editing an untranslated entry, the LFD command be automatically executed. If you set po-auto-edit-with-msgid to t, the translation gets initialised with the original string, in case none exists already. The default value for po-auto-edit-with-msgid is nil.

In fact, whether it is best to start a translation with an empty string, or rather with a copy of the original string, is a matter of taste or habit. Sometimes, the source language and the target language are so different that is simply best to start writing on an empty page. At other times, the source and target languages are so close that it would be a waste to retype a number of words already being written in the original string. A translator may also like having the original string right under her eyes, as she will progressively overwrite the original text with the translation, even if this requires some extra editing work to get rid of the original.

The command k (po-kill-msgstr) merely empties the translation string, so turning the entry into an untranslated one. But while doing so, its previous contents is put apart in a special place, known as the kill ring. The command w (po-kill-ring-save-msgstr) has also the effect of taking a copy of the translation onto the kill ring, but it otherwise leaves the entry alone, and does not remove the translation from the entry. Both commands use exactly the Emacs kill ring, which is shared between buffers, and which is well known already to Emacs lovers.

The translator may use k or w many times in the course of her work, as the kill ring may hold several saved translations. From the kill ring, strings may later be reinserted in various Emacs buffers. In particular, the kill ring may be used for moving translation strings between different entries of a single PO file buffer, or if the translator is handling many such buffers at once, even between PO files.

To facilitate exchanges with buffers which are not in PO mode, the translation string put on the kill ring by the k command is fully unquoted before being saved: external quotes are removed, multi-line strings are concatenated, and backslash escaped sequences are turned into their corresponding characters. In the special case of obsolete entries, the translation is also uncommented prior to saving.

The command y (po-yank-msgstr) completely replaces the translation of the current entry by a string taken from the kill ring. Following Emacs terminology, we then say that the replacement string is yanked into the PO file buffer. See Yanking in The Emacs Editor. The first time y is used, the translation receives the value of the most recent addition to the kill ring. If y is typed once again, immediately, without intervening keystrokes, the translation just inserted is taken away and replaced by the second most recent addition to the kill ring. By repeating y many times in a row, the translator may travel along the kill ring for saved strings, until she finds the string she really wanted.

When a string is yanked into a PO file entry, it is fully and automatically requoted for complying with the format PO files should have. Further, if the entry is obsolete, PO mode then appropriately push the inserted string inside comments. Once again, translators should not burden themselves with quoting considerations besides, of course, the necessity of the translated string itself respective to the program using it.

Note that k or w are not the only commands pushing strings on the kill ring, as almost any PO mode command replacing translation strings (or the translator comments) automatically saves the old string on the kill ring. The main exceptions to this general rule are the yanking commands themselves.

To better illustrate the operation of killing and yanking, let’s use an actual example, taken from a common situation. When the programmer slightly modifies some string right in the program, his change is later reflected in the PO file by the appearance of a new untranslated entry for the modified string, and the fact that the entry translating the original or unmodified string becomes obsolete. In many cases, the translator might spare herself some work by retrieving the unmodified translation from the obsolete entry, then initializing the untranslated entry msgstr field with this retrieved translation. Once this done, the obsolete entry is not wanted anymore, and may be safely deleted.

When the translator finds an untranslated entry and suspects that a slight variant of the translation exists, she immediately uses m to mark the current entry location, then starts chasing obsolete entries with o, hoping to find some translation corresponding to the unmodified string. Once found, she uses the DEL command for deleting the obsolete entry, knowing that DEL also kills the translation, that is, pushes the translation on the kill ring. Then, r returns to the initial untranslated entry, and y then yanks the saved translation right into the msgstr field. The translator is then free to use RET for fine tuning the translation contents, and maybe to later use u, then m again, for going on with the next untranslated string.

When some sequence of keys has to be typed over and over again, the translator may find it useful to become better acquainted with the Emacs capability of learning these sequences and playing them back under request. See Keyboard Macros in The Emacs Editor.

8.7.10 Modifying Comments

Any translation work done seriously will raise many linguistic difficulties, for which decisions have to be made, and the choices further documented. These documents may be saved within the PO file in form of translator comments, which the translator is free to create, delete, or modify at will. These comments may be useful to herself when she returns to this PO file after a while.

Comments not having whitespace after the initial ‘#’, for example, those beginning with ‘#.’ or ‘#:’, are not translator comments, they are exclusively created by other gettext tools. So, the commands below will never alter such system added comments, they are not meant for the translator to modify. See The Format of PO Files.

The following commands are somewhat similar to those modifying translations, so the general indications given for those apply here. See Modifying Translations.

# ¶

Interactively edit the translator comments (po-edit-comment).

K ¶

Save the translator comments on the kill ring, and delete it (po-kill-comment).

W ¶

Save the translator comments on the kill ring, without deleting it (po-kill-ring-save-comment).

Y ¶

Replace the translator comments, taking the new from the kill ring (po-yank-comment).

These commands parallel PO mode commands for modifying the translation strings, and behave much the same way as they do, except that they handle this part of PO file comments meant for translator usage, rather than the translation strings. So, if the descriptions given below are slightly succinct, it is because the full details have already been given. See Modifying Translations.

The command # (po-edit-comment) opens a new Emacs window containing a copy of the translator comments on the current PO file entry. If there are no such comments, PO mode understands that the translator wants to add a comment to the entry, and she is presented with an empty screen. Comment marks (#) and the space following them are automatically removed before edition, and reinstated after. For translator comments pertaining to obsolete entries, the uncommenting and recommenting operations are done twice. Once in the editing window, the keys C-c C-c allow the translator to tell she is finished with editing the comment. See Details of Sub Edition, for further details.

Functions found on po-subedit-mode-hook, if any, are executed after the string has been inserted in the edit buffer.

The command K (po-kill-comment) gets rid of all translator comments, while saving those comments on the kill ring. The command W (po-kill-ring-save-comment) takes a copy of the translator comments on the kill ring, but leaves them undisturbed in the current entry. The command Y (po-yank-comment) completely replaces the translator comments by a string taken at the front of the kill ring. When this command is immediately repeated, the comments just inserted are withdrawn, and replaced by other strings taken along the kill ring.

On the kill ring, all strings have the same nature. There is no distinction between translation strings and translator comments strings. So, for example, let’s presume the translator has just finished editing a translation, and wants to create a new translator comment to document why the previous translation was not good, just to remember what was the problem. Foreseeing that she will do that in her documentation, the translator may want to quote the previous translation in her translator comments. To do so, she may initialize the translator comments with the previous translation, still at the head of the kill ring. Because editing already pushed the previous translation on the kill ring, she merely has to type M-w prior to #, and the previous translation will be right there, all ready for being introduced by some explanatory text.

On the other hand, presume there are some translator comments already and that the translator wants to add to those comments, instead of wholly replacing them. Then, she should edit the comment right away with #. Once inside the editing window, she can use the regular Emacs commands C-y (yank) and M-y (yank-pop) to get the previous translation where she likes.

8.7.11 Details of Sub Edition

The PO subedit minor mode has a few peculiarities worth being described in fuller detail. It installs a few commands over the usual editing set of Emacs, which are described below.

C-c C-c ¶

Complete edition (po-subedit-exit).

C-c C-k ¶

Abort edition (po-subedit-abort).

C-c C-a ¶

Consult auxiliary PO files (po-subedit-cycle-auxiliary).

The window’s contents represents a translation for a given message, or a translator comment. The translator may modify this window to her heart’s content. Once this is done, the command C-c C-c (po-subedit-exit) may be used to return the edited translation into the PO file, replacing the original translation, even if it moved out of sight or if buffers were switched.

If the translator becomes unsatisfied with her translation or comment, to the extent she prefers keeping what was existent prior to the RET or # command, she may use the command C-c C-k (po-subedit-abort) to merely get rid of edition, while preserving the original translation or comment. Another way would be for her to exit normally with C-c C-c, then type U once for undoing the whole effect of last edition.

The command C-c C-a (po-subedit-cycle-auxiliary) allows for glancing through translations already achieved in other languages, directly while editing the current translation. This may be quite convenient when the translator is fluent at many languages, but of course, only makes sense when such completed auxiliary PO files are already available to her (see Consulting Auxiliary PO Files).

Functions found on po-subedit-mode-hook, if any, are executed after the string has been inserted in the edit buffer.

While editing her translation, the translator should pay attention to not inserting unwanted RET (newline) characters at the end of the translated string if those are not meant to be there, or to removing such characters when they are required. Since these characters are not visible in the editing buffer, they are easily introduced by mistake. To help her, RET automatically puts the character < at the end of the string being edited, but this < is not really part of the string. On exiting the editing window with C-c C-c, PO mode automatically removes such < and all whitespace added after it. If the translator adds characters after the terminating <, it looses its delimiting property and integrally becomes part of the string. If she removes the delimiting <, then the edited string is taken as is, with all trailing newlines, even if invisible. Also, if the translated string ought to end itself with a genuine <, then the delimiting < may not be removed; so the string should appear, in the editing window, as ending with two < in a row.

When a translation (or a comment) is being edited, the translator may move the cursor back into the PO file buffer and freely move to other entries, browsing at will. If, with an edition pending, the translator wanders in the PO file buffer, she may decide to start modifying another entry. Each entry being edited has its own subedit buffer. It is possible to simultaneously edit the translation and the comment of a single entry, or to edit entries in different PO files, all at once. Typing RET on a field already being edited merely resumes that particular edit. Yet, the translator should better be comfortable at handling many Emacs windows!

Pending subedits may be completed or aborted in any order, regardless of how or when they were started. When many subedits are pending and the translator asks for quitting the PO file (with the q command), subedits are automatically resumed one at a time, so she may decide for each of them.

8.7.12 C Sources Context

PO mode is particularly powerful when used with PO files created through GNU gettext utilities, as those utilities insert special comments in the PO files they generate. Some of these special comments relate the PO file entry to exactly where the untranslated string appears in the program sources.

When the translator gets to an untranslated entry, she is fairly often faced with an original string which is not as informative as it normally should be, being succinct, cryptic, or otherwise ambiguous. Before choosing how to translate the string, she needs to understand better what the string really means and how tight the translation has to be. Most of the time, when problems arise, the only way left to make her judgment is looking at the true program sources from where this string originated, searching for surrounding comments the programmer might have put in there, and looking around for helping clues of any kind.

Surely, when looking at program sources, the translator will receive more help if she is a fluent programmer. However, even if she is not versed in programming and feels a little lost in C code, the translator should not be shy at taking a look, once in a while. It is most probable that she will still be able to find some of the hints she needs. She will learn quickly to not feel uncomfortable in program code, paying more attention to programmer’s comments, variable and function names (if he dared choosing them well), and overall organization, than to the program code itself.

The following commands are meant to help the translator at getting program source context for a PO file entry.

s ¶

Resume the display of a program source context, or cycle through them (po-cycle-source-reference).

M-s ¶

Display of a program source context selected by menu (po-select-source-reference).

S ¶

Add a directory to the search path for source files (po-consider-source-path).

M-S ¶

Delete a directory from the search path for source files (po-ignore-source-path).

The commands s (po-cycle-source-reference) and M-s (po-select-source-reference) both open another window displaying some source program file, and already positioned in such a way that it shows an actual use of the string to be translated. By doing so, the command gives source program context for the string. But if the entry has no source context references, or if all references are unresolved along the search path for program sources, then the command diagnoses this as an error.

Even if s (or M-s) opens a new window, the cursor stays in the PO file window. If the translator really wants to get into the program source window, she ought to do it explicitly, maybe by using command O.

When s is typed for the first time, or for a PO file entry which is different of the last one used for getting source context, then the command reacts by giving the first context available for this entry, if any. If some context has already been recently displayed for the current PO file entry, and the translator wandered off to do other things, typing s again will merely resume, in another window, the context last displayed. In particular, if the translator moved the cursor away from the context in the source file, the command will bring the cursor back to the context. By using s many times in a row, with no other commands intervening, PO mode will cycle to the next available contexts for this particular entry, getting back to the first context once the last has been shown.

The command M-s behaves differently. Instead of cycling through references, it lets the translator choose a particular reference among many, and displays that reference. It is best used with completion, if the translator types TAB immediately after M-s, in response to the question, she will be offered a menu of all possible references, as a reminder of which are the acceptable answers. This command is useful only where there are really many contexts available for a single string to translate.

Program source files are usually found relative to where the PO file stands. As a special provision, when this fails, the file is also looked for, but relative to the directory immediately above it. Those two cases take proper care of most PO files. However, it might happen that a PO file has been moved, or is edited in a different place than its normal location. When this happens, the translator should tell PO mode in which directory normally sits the genuine PO file. Many such directories may be specified, and all together, they constitute what is called the search path for program sources. The command S (po-consider-source-path) is used to interactively enter a new directory at the front of the search path, and the command M-S (po-ignore-source-path) is used to select, with completion, one of the directories she does not want anymore on the search path.

8.7.13 Consulting Auxiliary PO Files

PO mode is able to help the knowledgeable translator, being fluent in many languages, at taking advantage of translations already achieved in other languages she just happens to know. It provides these other language translations as additional context for her own work. Moreover, it has features to ease the production of translations for many languages at once, for translators preferring to work in this way.

An auxiliary PO file is an existing PO file meant for the same package the translator is working on, but targeted to a different mother tongue language. Commands exist for declaring and handling auxiliary PO files, and also for showing contexts for the entry under work.

Here are the auxiliary file commands available in PO mode.

a ¶

Seek auxiliary files for another translation for the same entry (po-cycle-auxiliary).

C-c C-a ¶

Switch to a particular auxiliary file (po-select-auxiliary).

A ¶

Declare this PO file as an auxiliary file (po-consider-as-auxiliary).

M-A ¶

Remove this PO file from the list of auxiliary files (po-ignore-as-auxiliary).

Command A (po-consider-as-auxiliary) adds the current PO file to the list of auxiliary files, while command M-A (po-ignore-as-auxiliary just removes it.

The command a (po-cycle-auxiliary) seeks all auxiliary PO files, round-robin, searching for a translated entry in some other language having an msgid field identical as the one for the current entry. The found PO file, if any, takes the place of the current PO file in the display (its window gets on top). Before doing so, the current PO file is also made into an auxiliary file, if not already. So, a in this newly displayed PO file will seek another PO file, and so on, so repeating a will eventually yield back the original PO file.

The command C-c C-a (po-select-auxiliary) asks the translator for her choice of a particular auxiliary file, with completion, and then switches to that selected PO file. The command also checks if the selected file has an msgid field identical as the one for the current entry, and if yes, this entry becomes current. Otherwise, the cursor of the selected file is left undisturbed.

For all this to work fully, auxiliary PO files will have to be normalized, in that way that msgid fields should be written exactly the same way. It is possible to write msgid fields in various ways for representing the same string, different writing would break the proper behaviour of the auxiliary file commands of PO mode. This is not expected to be much a problem in practice, as most existing PO files have their msgid entries written by the same GNU gettext tools.

However, PO files initially created by PO mode itself, while marking strings in source files, are normalised differently. So are PO files resulting of the ‘M-x normalize’ command. Until these discrepancies between PO mode and other GNU gettext tools get fully resolved, the translator should stay aware of normalisation issues.

8.9.1 Creating Compendia

Basically every PO file consisting of translated entries only can be declared as a valid compendium. Often the translator wants to have special compendia; let’s consider two cases: concatenating PO files and extracting a message subset from a PO file.

• Concatenate PO Files
• Extract a Message Subset from a PO File

msgcat -o compendium.po file1.po file2.po

#: src/hello.c:200
#, c-format
msgid "Report bugs to <%s>.\n"
msgstr "Comunicar `bugs' a <%s>.\n"

#: src/bye.c:100
#, c-format
msgid "Report bugs to <%s>.\n"
msgstr "Comunicar \"bugs\" a <%s>.\n"

#: src/hello.c:200 src/bye.c:100
#, fuzzy, c-format
msgid "Report bugs to <%s>.\n"
msgstr ""
"#-#-#-#-#  file1.po  #-#-#-#-#\n"
"Comunicar `bugs' a <%s>.\n"
"#-#-#-#-#  file2.po  #-#-#-#-#\n"
"Comunicar \"bugs\" a <%s>.\n"

msgcat --use-first -o compendium.po file1.po file2.po

msggrep --location src/getopt.c -o compendium.po file.po

8.9.2 Using Compendia

You can use a compendium file to initialize a translation from scratch or to update an already existing translation.

• Initialize a New Translation File
• Update an Existing Translation File

msgmerge --compendium compendium.po -o file.po /dev/null file.pot

msgcat --use-first -o update.po compendium1.po compendium2.po file.po
msgmerge update.po file.pot | msgattrib --no-obsolete > file.po

9.1.1 Input file location

‘inputfile …’

Input files.

‘-f file’ ¶

‘--files-from=file’

Read the names of the input files from file instead of getting them from the command line.

‘-D directory’ ¶

‘--directory=directory’

Add directory to the list of directories. Source files are searched relative to this list of directories. The resulting .po file will be written relative to the current directory, though.

If inputfile is ‘-’, standard input is read.

9.1.2 Output file location

‘-o file’ ¶

‘--output-file=file’

Write output to specified file.

The results are written to standard output if no output file is specified or if it is ‘-’.

9.1.3 Message selection

‘-< number’ ¶

‘--less-than=number’

Print messages with less than number definitions, defaults to infinite if not set.

‘-> number’ ¶

‘--more-than=number’

Print messages with more than number definitions, defaults to 0 if not set.

‘-u’ ¶

‘--unique’

Shorthand for ‘--less-than=2’. Requests that only unique messages be printed.

9.1.4 Input file syntax

‘-P’ ¶

‘--properties-input’

Assume the input files are Java ResourceBundles in Java .properties syntax, not in PO file syntax.

‘--stringtable-input’ ¶

Assume the input files are NeXTstep/GNUstep localized resource files in .strings syntax, not in PO file syntax.

9.1.5 Output details

‘-t’ ¶

‘--to-code=name’

Specify encoding for output.

‘--use-first’ ¶

Use first available translation for each message. Don’t merge several translations into one.

‘--lang=catalogname’ ¶

Specify the ‘Language’ field to be used in the header entry. See Filling in the Header Entry for the meaning of this field. Note: The ‘Language-Team’ and ‘Plural-Forms’ fields are left unchanged.

‘--color’ ¶

‘--color=when’

Specify whether or when to use colors and other text attributes. See The --color option for details.

‘--style=style_file’ ¶

Specify the CSS style rule file to use for --color. See The --style option for details.

‘--force-po’ ¶

Always write an output file even if it contains no message.

‘-i’ ¶

‘--indent’

Write the .po file using indented style.

‘--no-location’ ¶

Do not write ‘#: filename:line’ lines.

‘-n’ ¶

‘--add-location=type’

Generate ‘#: filename:line’ lines (default).

The optional type can be either ‘full’, ‘file’, or ‘never’. If it is not given or ‘full’, it generates the lines with both file name and line number. If it is ‘file’, the line number part is omitted. If it is ‘never’, it completely suppresses the lines (same as --no-location).

‘--strict’ ¶

Write out a strict Uniforum conforming PO file. Note that this Uniforum format should be avoided because it doesn’t support the GNU extensions.

‘-p’ ¶

‘--properties-output’

Write out a Java ResourceBundle in Java .properties syntax. Note that this file format doesn’t support plural forms and silently drops obsolete messages.

‘--stringtable-output’ ¶

Write out a NeXTstep/GNUstep localized resource file in .strings syntax. Note that this file format doesn’t support plural forms.

‘-w number’ ¶

‘--width=number’

Set the output page width. Long strings in the output files will be split across multiple lines in order to ensure that each line’s width (= number of screen columns) is less or equal to the given number.

‘--no-wrap’ ¶

Do not break long message lines. Message lines whose width exceeds the output page width will not be split into several lines. Only file reference lines which are wider than the output page width will be split.

‘-s’ ¶

‘--sort-output’

Generate sorted output. Note that using this option makes it much harder for the translator to understand each message’s context.

‘-F’ ¶

‘--sort-by-file’

Sort output by file location.

9.1.6 Informative output

‘-h’ ¶

‘--help’

Display this help and exit.

‘-V’ ¶

‘--version’

Output version information and exit.

9.2.1 Input file location

‘inputfile’

Input PO file.

‘-D directory’ ¶

‘--directory=directory’

Add directory to the list of directories. Source files are searched relative to this list of directories. The resulting .po file will be written relative to the current directory, though.

If no inputfile is given or if it is ‘-’, standard input is read.

9.2.2 Output file location

‘-o file’ ¶

‘--output-file=file’

Write output to specified file.

The results are written to standard output if no output file is specified or if it is ‘-’.

9.2.3 Conversion target

‘-t’ ¶

‘--to-code=name’

Specify encoding for output.

The default encoding is the current locale’s encoding.

9.2.4 Input file syntax

‘-P’ ¶

‘--properties-input’

Assume the input file is a Java ResourceBundle in Java .properties syntax, not in PO file syntax.

‘--stringtable-input’ ¶

Assume the input file is a NeXTstep/GNUstep localized resource file in .strings syntax, not in PO file syntax.

9.2.5 Output details

‘--color’ ¶

‘--color=when’

Specify whether or when to use colors and other text attributes. See The --color option for details.

‘--style=style_file’ ¶

Specify the CSS style rule file to use for --color. See The --style option for details.

‘--force-po’ ¶

Always write an output file even if it contains no message.

‘-i’ ¶

‘--indent’

Write the .po file using indented style.

‘--no-location’ ¶

Do not write ‘#: filename:line’ lines.

‘-n’ ¶

‘--add-location=type’

Generate ‘#: filename:line’ lines (default).

The optional type can be either ‘full’, ‘file’, or ‘never’. If it is not given or ‘full’, it generates the lines with both file name and line number. If it is ‘file’, the line number part is omitted. If it is ‘never’, it completely suppresses the lines (same as --no-location).

‘--strict’ ¶

Write out a strict Uniforum conforming PO file. Note that this Uniforum format should be avoided because it doesn’t support the GNU extensions.

‘-p’ ¶

‘--properties-output’

Write out a Java ResourceBundle in Java .properties syntax. Note that this file format doesn’t support plural forms and silently drops obsolete messages.

‘--stringtable-output’ ¶

Write out a NeXTstep/GNUstep localized resource file in .strings syntax. Note that this file format doesn’t support plural forms.

‘-w number’ ¶

‘--width=number’

Set the output page width. Long strings in the output files will be split across multiple lines in order to ensure that each line’s width (= number of screen columns) is less or equal to the given number.

‘--no-wrap’ ¶

Do not break long message lines. Message lines whose width exceeds the output page width will not be split into several lines. Only file reference lines which are wider than the output page width will be split.

‘-s’ ¶

‘--sort-output’

Generate sorted output. Note that using this option makes it much harder for the translator to understand each message’s context.

‘-F’ ¶

‘--sort-by-file’

Sort output by file location.

9.2.6 Informative output

‘-h’ ¶

‘--help’

Display this help and exit.

‘-V’ ¶

‘--version’

Output version information and exit.

9.3.1 Input file location

‘inputfile’

Input PO file.

‘-D directory’ ¶

‘--directory=directory’

Add directory to the list of directories. Source files are searched relative to this list of directories. The resulting .po file will be written relative to the current directory, though.

If no inputfile is given or if it is ‘-’, standard input is read.

9.3.2 Output file location

‘-o file’ ¶

‘--output-file=file’

Write output to specified file.

The results are written to standard output if no output file is specified or if it is ‘-’.

9.3.3 Message selection

  [-N sourcefile]... [-M domainname]...
  [-J msgctxt-pattern] [-K msgid-pattern] [-T msgstr-pattern]
  [-C comment-pattern]

A message is selected if

• it comes from one of the specified source files,
• or if it comes from one of the specified domains,
• or if ‘-J’ is given and its context (msgctxt) matches msgctxt-pattern,
• or if ‘-K’ is given and its key (msgid or msgid_plural) matches msgid-pattern,
• or if ‘-T’ is given and its translation (msgstr) matches msgstr-pattern,
• or if ‘-C’ is given and the translator’s comment matches comment-pattern.

When more than one selection criterion is specified, the set of selected messages is the union of the selected messages of each criterion.

msgctxt-pattern or msgid-pattern or msgstr-pattern syntax:

  [-E | -F] [-e pattern | -f file]...

patterns are basic regular expressions by default, or extended regular expressions if -E is given, or fixed strings if -F is given.

‘-N sourcefile’ ¶

‘--location=sourcefile’

Select messages extracted from sourcefile. sourcefile can be either a literal file name or a wildcard pattern.

‘-M domainname’ ¶

‘--domain=domainname’

Select messages belonging to domain domainname.

‘-J’ ¶

‘--msgctxt’

Start of patterns for the msgctxt.

‘-K’ ¶

‘--msgid’

Start of patterns for the msgid.

‘-T’ ¶

‘--msgstr’

Start of patterns for the msgstr.

‘-C’ ¶

‘--comment’

Start of patterns for the translator’s comment.

‘-X’ ¶

‘--extracted-comment’

Start of patterns for the extracted comments.

‘-E’ ¶

‘--extended-regexp’

Specify that pattern is an extended regular expression.

‘-F’ ¶

‘--fixed-strings’

Specify that pattern is a set of newline-separated strings.

‘-e pattern’ ¶

‘--regexp=pattern’

Use pattern as a regular expression.

‘-f file’ ¶

‘--file=file’

Obtain pattern from file.

‘-i’ ¶

‘--ignore-case’

Ignore case distinctions.

‘-v’ ¶

‘--invert-match’

Output only the messages that do not match any selection criterion, instead of the messages that match a selection criterion.

9.3.4 Input file syntax

‘-P’ ¶

‘--properties-input’

Assume the input file is a Java ResourceBundle in Java .properties syntax, not in PO file syntax.

‘--stringtable-input’ ¶

Assume the input file is a NeXTstep/GNUstep localized resource file in .strings syntax, not in PO file syntax.

9.3.5 Output details

‘--color’ ¶

‘--color=when’

Specify whether or when to use colors and other text attributes. See The --color option for details.

‘--style=style_file’ ¶

Specify the CSS style rule file to use for --color. See The --style option for details.

‘--force-po’ ¶

Always write an output file even if it contains no message.

‘--indent’ ¶

Write the .po file using indented style.

‘--no-location’ ¶

Do not write ‘#: filename:line’ lines.

‘-n’ ¶

‘--add-location=type’

Generate ‘#: filename:line’ lines (default).

The optional type can be either ‘full’, ‘file’, or ‘never’. If it is not given or ‘full’, it generates the lines with both file name and line number. If it is ‘file’, the line number part is omitted. If it is ‘never’, it completely suppresses the lines (same as --no-location).

‘--strict’ ¶

Write out a strict Uniforum conforming PO file. Note that this Uniforum format should be avoided because it doesn’t support the GNU extensions.

‘-p’ ¶

‘--properties-output’

Write out a Java ResourceBundle in Java .properties syntax. Note that this file format doesn’t support plural forms and silently drops obsolete messages.

‘--stringtable-output’ ¶

Write out a NeXTstep/GNUstep localized resource file in .strings syntax. Note that this file format doesn’t support plural forms.

‘-w number’ ¶

‘--width=number’

Set the output page width. Long strings in the output files will be split across multiple lines in order to ensure that each line’s width (= number of screen columns) is less or equal to the given number.

‘--no-wrap’ ¶

Do not break long message lines. Message lines whose width exceeds the output page width will not be split into several lines. Only file reference lines which are wider than the output page width will be split.

‘--sort-output’ ¶

Generate sorted output. Note that using this option makes it much harder for the translator to understand each message’s context.

‘--sort-by-file’ ¶

Sort output by file location.

9.3.6 Informative output

‘-h’ ¶

‘--help’

Display this help and exit.

‘-V’ ¶

‘--version’

Output version information and exit.

9.3.7 Examples

To extract the messages that come from the source files gnulib-lib/error.c and gnulib-lib/getopt.c:

msggrep -N gnulib-lib/error.c -N gnulib-lib/getopt.c input.po

To extract the messages that contain the string “Please specify” in the original string:

msggrep --msgid -F -e 'Please specify' input.po

To extract the messages that have a context specifier of either “Menu>File” or “Menu>Edit” or a submenu of them:

msggrep --msgctxt -E -e '^Menu>(File|Edit)' input.po

To extract the messages whose translation contains one of the strings in the file wordlist.txt:

msggrep --msgstr -F -f wordlist.txt input.po

9.4.1 Input file location

‘-i inputfile’ ¶

‘--input=inputfile’

Input PO file.

‘-D directory’ ¶

‘--directory=directory’

Add directory to the list of directories. Source files are searched relative to this list of directories. The resulting .po file will be written relative to the current directory, though.

If no inputfile is given or if it is ‘-’, standard input is read.

9.4.2 Output file location

‘-o file’ ¶

‘--output-file=file’

Write output to specified file.

The results are written to standard output if no output file is specified or if it is ‘-’.

9.4.3 The filter

The filter can be any program that reads a translation from standard input and writes a modified translation to standard output. A frequently used filter is ‘sed’. A few particular built-in filters are also recognized.

‘--newline’ ¶

Add newline at the end of each input line and also strip the ending newline from the output line.

Note: If the filter is not a built-in filter, you have to care about encodings: It is your responsibility to ensure that the filter can cope with input encoded in the translation catalog’s encoding. If the filter wants input in a particular encoding, you can in a first step convert the translation catalog to that encoding using the ‘msgconv’ program, before invoking ‘msgfilter’. If the filter wants input in the locale’s encoding, but you want to avoid the locale’s encoding, then you can first convert the translation catalog to UTF-8 using the ‘msgconv’ program and then make ‘msgfilter’ work in an UTF-8 locale, by using the LC_ALL environment variable.

Note: Most translations in a translation catalog don’t end with a newline character. For this reason, unless the --newline option is used, it is important that the filter recognizes its last input line even if it ends without a newline, and that it doesn’t add an undesired trailing newline at the end. The ‘sed’ program on some platforms is known to ignore the last line of input if it is not terminated with a newline. You can use GNU sed instead; it does not have this limitation.

9.4.4 Useful filter-options when the filter is ‘sed’

‘-e script’ ¶

‘--expression=script’

Add script to the commands to be executed.

‘-f scriptfile’ ¶

‘--file=scriptfile’

Add the contents of scriptfile to the commands to be executed.

‘-n’ ¶

‘--quiet’

‘--silent’

Suppress automatic printing of pattern space.

9.4.5 Built-in filters

The filter ‘recode-sr-latin’ is recognized as a built-in filter. The command ‘recode-sr-latin’ converts Serbian text, written in the Cyrillic script, to the Latin script. The command ‘msgfilter recode-sr-latin’ applies this conversion to the translations of a PO file. Thus, it can be used to convert an sr.po file to an sr@latin.po file.

The filter ‘quot’ is recognized as a built-in filter. The command ‘msgfilter quot’ converts any quotations surrounded by a pair of ‘"’, ‘'’, and ‘`’.

The filter ‘boldquot’ is recognized as a built-in filter. The command ‘msgfilter boldquot’ converts any quotations surrounded by a pair of ‘"’, ‘'’, and ‘`’, also adding the VT100 escape sequences to the text to decorate it as bold.

The use of built-in filters is not sensitive to the current locale’s encoding. Moreover, when used with a built-in filter, ‘msgfilter’ can automatically convert the message catalog to the UTF-8 encoding when needed.

9.4.6 Input file syntax

‘-P’ ¶

‘--properties-input’

Assume the input file is a Java ResourceBundle in Java .properties syntax, not in PO file syntax.

‘--stringtable-input’ ¶

Assume the input file is a NeXTstep/GNUstep localized resource file in .strings syntax, not in PO file syntax.

9.4.7 Output details

‘--color’ ¶

‘--color=when’

Specify whether or when to use colors and other text attributes. See The --color option for details.

‘--style=style_file’ ¶

Specify the CSS style rule file to use for --color. See The --style option for details.

‘--force-po’ ¶

Always write an output file even if it contains no message.

‘--indent’ ¶

Write the .po file using indented style.

‘--keep-header’ ¶

Keep the header entry, i.e. the message with ‘msgid ""’, unmodified, instead of filtering it. By default, the header entry is subject to filtering like any other message.

‘--no-location’ ¶

Do not write ‘#: filename:line’ lines.

‘-n’ ¶

‘--add-location=type’

Generate ‘#: filename:line’ lines (default).

The optional type can be either ‘full’, ‘file’, or ‘never’. If it is not given or ‘full’, it generates the lines with both file name and line number. If it is ‘file’, the line number part is omitted. If it is ‘never’, it completely suppresses the lines (same as --no-location).

‘--strict’ ¶

Write out a strict Uniforum conforming PO file. Note that this Uniforum format should be avoided because it doesn’t support the GNU extensions.

‘-p’ ¶

‘--properties-output’

Write out a Java ResourceBundle in Java .properties syntax. Note that this file format doesn’t support plural forms and silently drops obsolete messages.

‘--stringtable-output’ ¶

Write out a NeXTstep/GNUstep localized resource file in .strings syntax. Note that this file format doesn’t support plural forms.

‘-w number’ ¶

‘--width=number’

Set the output page width. Long strings in the output files will be split across multiple lines in order to ensure that each line’s width (= number of screen columns) is less or equal to the given number.

‘--no-wrap’ ¶

Do not break long message lines. Message lines whose width exceeds the output page width will not be split into several lines. Only file reference lines which are wider than the output page width will be split.

‘-s’ ¶

‘--sort-output’

Generate sorted output. Note that using this option makes it much harder for the translator to understand each message’s context.

‘-F’ ¶

‘--sort-by-file’

Sort output by file location.