What does #, fuzzy mean at the top of a xgettext-generated .pot file?

Question

When using xgettext to generate a .pot file, at the top of the generated file I get this:

# SOME DESCRIPTIVE TITLE.
...
#, fuzzy
...

What does the #, fuzzy mean?

I know what it means if a translation is fuzzy (it is poor quality), but what does it mean at the top of a .pot file?

Answer 1

So, what is this?

# SOME DESCRIPTIVE TITLE.
# Copyright (C) YEAR THE PACKAGE'S COPYRIGHT HOLDER
# This file is distributed under the same license as the PACKAGE package.
# FIRST AUTHOR <EMAIL@ADDRESS>, YEAR.
#
#, fuzzy
msgid ""
msgstr ""
"Project-Id-Version: PACKAGE VERSION\n"
"Report-Msgid-Bugs-To: \n"
"POT-Creation-Date: 2017-06-08 11:51-0400\n"
"PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n"
"Last-Translator: FULL NAME <EMAIL@ADDRESS>\n"
"Language-Team: LANGUAGE <LL@li.org>\n"
"Language: \n"
"MIME-Version: 1.0\n"
"Content-Type: text/plain; charset=CHARSET\n"
"Content-Transfer-Encoding: 8bit\n"

It's the header entry. It should be the first entry. And it must be the only entry with empty msgid (the docs).

An empty untranslated-string is reserved to contain the header entry with the meta information (see Filling in the Header Entry). This header entry should be the first entry of the file. The empty untranslated-string is reserved for this purpose and must not be used anywhere else.

The first "" in msgstr is added to have all the lines of the value aligned with each other. And the value is a multiline string. Multiline strings can be used in other entries in a similar way.

In this example, the empty string is used on the first line, to allow better alignment of the H from the word ‘Here’ over the f from the word ‘for’. In this example, the msgid keyword is followed by three strings, which are meant to be concatenated. Concatenating the empty string does not change the resulting overall string, but it is a way for us to comply with the necessity of msgid to be followed by a string on the same line, while keeping the multi-line presentation left-justified, as we find this to be a cleaner disposition. The empty string could have been omitted, but only if the string starting with ‘Here’ was promoted on the first line, right after msgid. It was not really necessary either to switch between the two last quoted strings immediately after the newline ‘\n’, the switch could have occurred after any other character, we just did it this way because it is neater.

And apparently the entry is marked as fuzzy to tell translators that it should be filled in.

Answer 2

xgettext adds the #, fuzzy entry at the top when it auto-generates a project header in the message file. The comment has no special meaning, per se: it's just noting that a human needs to come along and fill in the gaps.

Let's dig a little deeper into the source.

When you first create a message file, xgettext adds project information to the top of the generated message file (unless you pass --omit-header):

$ cat hello.c
int main() {
  printf(gettext("Hello World\n"));
  return 0;
}

$ xgettext -o- hello.c
# SOME DESCRIPTIVE TITLE.
# Copyright (C) YEAR THE PACKAGE'S COPYRIGHT HOLDER
# This file is distributed under the same license as the PACKAGE package.
# FIRST AUTHOR <EMAIL@ADDRESS>, YEAR.
#
#, fuzzy
msgid ""
msgstr ""
"Project-Id-Version: PACKAGE VERSION\n"
"Report-Msgid-Bugs-To: \n"
"POT-Creation-Date: 2017-06-08 11:51-0400\n"
"PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n"
"Last-Translator: FULL NAME <EMAIL@ADDRESS>\n"
"Language-Team: LANGUAGE <LL@li.org>\n"
"Language: \n"
"MIME-Version: 1.0\n"
"Content-Type: text/plain; charset=CHARSET\n"
"Content-Transfer-Encoding: 8bit\n"

#: hello.c:3
#, c-format
msgid "Hello World\n"
msgstr ""

The logic backing this is found in xgettext.c:construct_header(). Way down at the bottom of that function, the newly-generated header information is marked fuzzy:

mp->is_fuzzy = true;

Since this text has been marked as fuzzy, the #, fuzzy comment tag is added to the text. The intent here is to raise awareness: a computer program added text to the message file, and a human needs to take action. In particular, a human needs to come along and fill in the blanks: revision date, translator name, language, and so on.

Using the "#, fuzzy" annotation makes sense in this context, as per the docs:

[Fuzzy entries] usually call for revision by the translator.

Answer 3

From gettext on Fuzzy-Entries:

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.

I have seen #, fuzzy appear in when generating a message file (.po) using Django, and where the original text (msgid) was changed, in which case the translator should be aware that the translated text should be changed as well.