Each message in the previous example also contains the source reference comment, which is the line starting with #: above the msgid "..." line. It tells from which source file of the program code (or source document of any kind), and the line in that source file, the message has been extracted into the PO file. This piece of data may look strange at first--of what use is it to translators, to merit inclusion in the PO file? Since the PO format has been developed in context of free software, the source reference enables you to actually look up the message in the source file, when you need more context to translate a certain message. This does not require of you to be a programmer, as source code is frequently readable enough to infer the message context without actually understanding the code.

For example, in the translation the text in title position may need to have a certain grammatical or ortographical form, and it may not be apparent from the PO file alone if the message:

#: addcatdialog.cpp:45
msgid "Import Catalog"
msgstr ""

is used in title position. By following the source reference, you find this statement in the source file addcatdialog.cpp, line 45:

setCaption( i18n( "Import Catalog" ) );

The setCaption(...) bit makes it highly likely that the message is indeed being used in a title position. Some dedicated PO editors provide ways to quickly and comfortably look up source references, just by pressing a keyboard shortcut, which makes this approach to context determination that much easier.

When a message is long or contains some logical line-breaks, its original and translation strings may be wrapped in the PO file (with wrapping boundary usually at column 80), such as this:

#: indimenu.cpp:96
msgid ""
"No INDI devices currently running. To run devices, please select devices "
"from the Device Manager in the devices menu."
msgstr ""

This wrapping is entirely invisible to the consumer of the PO file. PO processing tools introduce wrapping mostly as a convenience to translators who like to work on PO files with plain text editors. This means that you are free to wrap the translation (the msgstr string) in the same way, differently, or not to wrap it at all. You should only not forget to enclose each wrapped line in double quotes, same as it is done for msgid. For example, this translation of the previous message:

#: indimenu.cpp:96
msgid ""
"No INDI devices (...)"
"(...) in the devices menu."
msgstr ""
"Nema INDI uređaja (...)"
"(...) u meniju uređaja."

is equivalent to this one:

#: indimenu.cpp:96
msgid ""
"No INDI devices (...)"
"(...) in the devices menu."
msgstr "Nema INDI uređaja (...) u meniju uređaja."

Dedicated PO editors may even not show wrapping to the translator, or wrap lines on their own independently of the underlying PO file. Curiosly enough, most PO editors seem to follow the original wrapping, at least by default. At any rate, if you would like to have all strings non-wrapped (including msgid) or vice versa, there are command line tools to achieve this.

A message in the PO file is uniquely identified by its msgid string (this is not entirely true, as will be explained shortly, but consider it approximately true for the moment). This means that, as the source which is translated evolves in time, a message may change some of its elements or the position within the PO file, but as long as it has the same msgid string, it is the same message. Those other, non-identifying elements include the translation (msgstr string), source reference comments, etc. Position means either the line number in the PO file, or relative position to other messages.

The first consequence of this fact is that the only reliable way to report a message to someone is to state its msgid string, in full or in sufficient part, even if the other person has access to the PO file where the message is found.^[3] Newcomer translators are sometimes not briefed about this, and then they at first report the line number of the message, or its ordinal number in the range of all messages, without giving the msgid. Line numbers cannot work because, for example, of the arbitrary line wrapping as described previously. Ordinal numbers do not work because your PO file may be slightly older or newer than that of the other person, and the ordinals may have changed in the meantime.

The second consequence is that there cannot be two messages with the same msgid in the same PO file (again not exactly true, see later). If the same text has been used two or more times in the source, then in the PO file it will appear as a single message, with its source reference comment (#:) listing all appearances. For example, the source reference of this message:

#: colorscheme.cpp:79 skycomponents/equator.cpp:31
msgid "Equator"
msgstr ""

shows that it is used at two places in the program source code. This feature of the PO format prevents needless duplication of work, by assuring that any duplicate text in the source is translated only once. This efficiency optimization can sometimes be a double-edged sword, but with an elegant solution for the problem that can arise, as you will see shortly.

The third, so to say, consequence, though more of a remark for clarity, is this: you should never modify the msgid string. Not only that doing so would have no purpose, but if the msgid is modified, the consumer of the translated PO file will not see the message as translated, since it will fetch messages by matching their msgid strings.

One place where explicit context provided by the authors can be found in a message, is within extracted comments, which start with #.. For example, the message:

#. TRANSLATORS: A test phrase with all letters of the English alphabet.
#. Replace it with a sample text in your language, such that it is
#. representative of language's writing system.
#: kdeui/fonts/kfontchooser.cpp:382
msgid "The Quick Brown Fox Jumps Over The Lazy Dog"
msgstr ""

has an extracted comment which tells you to avoid translating the English phrase for what it is, but to instead construct a phrase with the described property in your language.

This kind of context usually begins with an agreed-upon keyword, which in the above case is TRANSLATORS:, which is recommended by Gettext, but in principle depends on the source environment. It could be, for example, i18n: (short for "internationalization").

Extracted comments can sometimes be added not by a human author, but by a tool used to create or process PO files. For example, when markup-text documents are translated, such as HTML, or Docbook for documentation, the extracted comment frequently states the tag which wraps the text in the original document:

#. Tag: title
#: skycoords.docbook:73
msgid "The Horizontal Coordinate System"
msgstr ""

In this example, the #. Tag: title comment informs you that the message is a title, so that you can adjust the translation accordingly.

Another frequent example where processing tools provide extracted comments is when the PO file is created in a slightly roundabout way, such that source references do not really point to the source file, but to a temporary source file which existed only during the creation of the PO file. To make this less misleading, the extracted comment may state the true source:

#. i18n: file: tools/observinglist.ui:263
#. i18n: ectx: property (toolTip), widget (KPushButton, ScopeButton)
#: rc.cpp:5865
msgid "Point telescope at highlighted object"
msgstr ""

Here rc.cpp:5865 is the reference to the temporary source file, whereas the true source file is given as file: tools/observinglist.ui:263. (The other automatically extracted comment, ectx: ..., may look a bit cryptic, but you can still easily conclude from it that this message is a tooltip for a push button.)

Consider the following two messages from an program user interface:

#. TRANSLATORS: First letter in 'Scope'
#: tools/observinglist.cpp:700
msgid "S"
msgstr ""
⁠
#. TRANSLATORS: South
#: skycomponents/horizoncomponent.cpp:429
msgid "S"
msgstr ""

At first sight, you could think that it was nice of the programmer to add the explicit context (#. TRANSLATORS: ... lines), informing that the "S" of the first message is short for "Scope", and the "S" of the second message short for "South", so that translators know that they should use the letters corresponding to these words in their languages. But, can you spot the problem?

The problem is that these messages cannot be part of a valid PO file, since, as it was mentioned earlier, all messages must have unique msgid strings. Instead, in a real PO file, these two messages would be collapsed into one:

#. TRANSLATORS: First letter in 'Scope'
#. TRANSLATORS: South
#: tools/observinglist.cpp:700 skycomponents/horizoncomponent.cpp:429
msgid "S"
msgstr ""

Both contexts are still present, translators are still well informed, but it is now required that the words "Scope" and "South" also begin with the same letter in the target language--an extremely unlikely proposal.

In situations such as this, the programmer can equip messages with a different type of context, the disambiguating context. These contexts are no longer presented as extracted comments, but through another keyword string, the msgctxt:

#: tools/observinglist.cpp:700
msgctxt "First letter in 'Scope'"
msgid "S"
msgstr ""
⁠
#: skycomponents/horizoncomponent.cpp:429
msgctxt "South"
msgid "S"
msgstr ""

This is now a valid PO file, and you can translate each "S" on its own.

This updates the earlier approximation that messages must be unique by msgid strings to the real requirement: messages must be unique by the combination of msgctxt and msgid strings. If the msgctxt string is missing, as it usually is, you can think of it as being present but null-valued.^[4]

A rather frequent example of need for disambiguating contexts is when the original text is a single adjective in English, and used at several places in the source:

#: utils/kateautoindent.cpp:78 utils/katestyletreewidget.cpp:132
msgid "Normal"
msgstr ""

In many languages the adjective form must match the gender of the noun to which it refers, so if the "Normal" above refers both to indentation mode and text style, it is almost certainly necessary to provide disambiguating contexts:

#: utils/katestyletreewidget.cpp:132
msgctxt "Text style"
msgid "Normal"
msgstr "običan"
⁠
#: utils/kateautoindent.cpp:78
msgctxt "Autoindent mode"
msgid "Normal"
msgstr "obično"

You can imagine that programmers in general cannot know when a certain phrase, same in English when used in two contexts, needs different translations in some other language. This means that you, the translator, should inform them to add a disambiguating context when you determine that you need one.^[5]

At the moment of this writing, the msgctxt string is one of the younger additions to the PO format. But the need for disambiguating contexts was observed much earlier, and different translation environments have historically used different custom solutions to provide them. Such older PO files can still be encountered, so it is useful to present a few examples of custom disambiguating contexts. Before the msgctxt was introduced, messages indeed had to be unique by msgid alone, so disambiguating context had to be a part of the msgid, embedded with some special syntax. Here is how the first message from the previous example would look like in a PO file comming from a KDE program of circa 2006:

#: utils/katestyletreewidget.cpp:132
msgid ""
"_⁠: Text style\n"
"Normal"
msgstr "običan"

The disambiguating context has been embedded at the beginning of the msgid, surrounded by _⁠: ...\n. In a contemporary Gnome program, the same message would look something like this:

#: utils/gatestyletreewidget.c:132
msgid "Text style|Normal"
msgstr "običan"

Here the context is again at the beginning of msgid, but it is separated from the text only by the pipe character (|).

Sometimes you will need to translate a message without explicit context in a non-obvious way, after you have determined that such translation is needed by looking into the source or seeing the message in user interface at runtime. This may present a difficulty when the message is revisited, for example, by a proof-reader in the review process, or by another translator if the message got modified later on. This other person may conclude that the translation is wrong and "fix" it, or at the very least waste time by asking around why it was translated in that way.

Conversely, sometimes you may be unsure if your translation is exactly correct, for example if you have correctly guessed the context, or whether you have used correct terminology. In that case you can, of course, consult with fellow translators, but this would break you out of the "flow" state while working. It is better if such communication is delayed to the moment when the translation of the PO file is otherwise complete.

For these situations, you can write down your own inferred context, doubts or notes, in another type of comment, the translator comment. These comments start simply with # (hash and space), followed by any text whatsoever. As with other comments, there may be any number of them. A hypothetical example:

# Wikipedia says that ‘etrurski’ is our name for this script.
#: viewpart/UnicodeBlocks.h:151
msgid "Old Italic"
msgstr "etrurski"

In reality, a translator comment such as the one above would probably be written in the language of translation, as there is no reason for it to be in English. This is not to say that translator comments should never be in English, there may be situations when that could be advantageous.

It is particularly important to know that translator comments are the only type of comment that all well-behaved PO processing tools are guaranteed to preserve in the same way as translation. For example, if you would write something into an extracted comment (#.), it would very soon dissapear in one of the standard maintenance procedures. So make sure you add any personal remarks into translator comments, and nowhere else.

When a file manager shows a message like "Really delete file tmp10.txt?" or "Open with Froobaz", the "tmp10.txt" and "Froobaz" parts had to be added to the rest of the text at runtime. In such cases, the original text as seen by the translator will contain format directives, substrings which the program will replace with dynamically determined arguments to complete the message to be shown to the user.

For example, in the PO file comming from a KDE program, there will be messages like this one:

#: skycomponents/constellationlines.cpp:106
#, kde-format
msgid "No star named %1 found."
msgstr "Nema zvezde po imenu %1."

The format directive in this message is %1, and it will be substituted at runtime with the text provided by the user as the name to search for. If several arguments need to be substituted in the text, there can be more format directives with increasing numbers: %1, %2, %3...

A new type of comment has appeared as well, the flags comment. This comment begins with #,, followed by the comma-separated list of keywords--the flags--which clarify the state or the type of the message. In this example the flag is kde-format, indicating that format directives in the message are of KDE type.

Format directives differ across source environments, but they are usually easy to recognize. The previous message, if it would be found in a Gnome program, would look like this:

#: skycomponents/constellationlines.c:106
#, c-format
msgid "No star named %s found."
msgstr "Nema zvezde po imenu %s."

The format directive changed to %s, and the format flag to c-format. This is the format used by most programs written in C, and by many written in C++. In C format, the %s directive is for substituting string arguments, and another frequent directive is %d for integer numbers; but there are many more.

For one more example, to illustrate the diversity of format directives, if the program would have been written in Python the message could look like:

#: skycomponents/constellationlines.cpp:106
#, python-format
msgid "No star named %(starname)s found."
msgstr "Nema zvezde po imenu %(starname)s."

Here the format directive is %(starname)s, which indicates the argument type similar to C format (%s), but also its name in parenthesis. Hence the python-format flag. This name must not be changed in translation, as otherwise the program will not be able to match the directive and make the substitute. This would probably make the program crash when it tries to display the message.

You only need to make sure that each directive from the original string is found in the translation, and very rarely to modify the directives themselves. Format flags, such as kde-format, c-format, etc., are there not only as information for translators, but they are also used by tools for validating PO files. For example, if you forget or mistype a format directive in the translation, such tools will report it. Dedicated PO editors may warn on the spot, or when saving the PO file. This provides you with a "safety net", so long as you remember to perform the checks after completing the translation (if the PO editor does not do it automatically).

One situation that may require modification of directives is when there are several of them, and they need to be ordered differently in the translation:

#: kxsldbgpart/libxsldbg/xsldbg.cpp:256
#, kde-format
msgid "%1 took %2 ms to complete."
msgstr "Trebalo je %2 ms da se %1 završi."

With KDE format directives, which are numbered, reordering is as simple as above. Similarly for the Python format, where directives are named. But for formats where directives are neither numbered nor named by default, like in C format (where they only state argument type), you can sometimes modify directives to the desired effect:

#: gxsldbgpart/libxsldbg/xsldbg.c:256
#, c-format
msgid "%s took %d ms to complete."
msgstr "Trebalo je %2$d ms da se %1$s završi."

If the directives are numbered or named, and there is more than one same-number or same-name directive, usually any of the duplicates can be dropped in the translation. This may be useful in a longer text, for example when in the translation a pronoun can be safely used instead of repeating the argument:

#: hypothetical.cpp:100
#, kde-format
msgid "%1 is the blah, blah, blah. With %1 you can blah, blah."
msgstr "%1 je bla, bla, bla. Pomoću njega možete bla, bla."

Here "njega" is a pronoun used instead of repeating the %1. Conversely, it is possible to repeat the directive where the original text had used a pronoun, if it better fits the translation.

Sometimes, instead of using a format directive, the programmer may try to concatenate the full text out of separate messages:

#: hypothetical.cpp:100
msgid "No star named "
msgstr ""
⁠
#: hypothetical.cpp:100
msgid " found."
msgstr ""

Here the program will fetch the first message, append to it the argument, and then append the second message. This kind of programming is considered as one of the basic errors when making a translatable program, because it forces translators to "piece the puzzle", which may not even be possible in every language. This is thankfully rare today, but when it does happen, while you can try to work around, it is better that you contact the authors to have the source code fixed.

Programs sometimes show parts of the text in non-plain text: certain words may be italic or bold, titles in larger font size, list items with graphical bullets, etc. This is frequent, for example, in tooltips and message boxes. Yet richer typographic elements of this kind are usually found in documentation and other static content, which may need to be suitable both for reading on screen and printing on paper. In such messages, the original text will contain markup, where words, phrases, and whole paragraphs are wrapped with special tags.

The following messages show typical examples of markup in program user interface:

#: rc.cpp:1632 rc.cpp:3283
msgid "<b>Name:</b>"
msgstr ""
⁠
#: kgeography.cpp:375
#, kde-format
msgid "<qt>Current map:<br/><b>%1</b></qt>"
msgstr ""
⁠
#: rc.cpp:2537 rc.cpp:4188
msgid ""
"<b>Tip</b><br/>Some non-Meade telescopes support a subset of the LX200 "
"command set. Select <tt>LX200 Basic</tt> to control such devices."
msgstr ""

The markup in these messages is XML-like, where tags for visual formatting are specified as <tag>...</tag> wrappings around the visible text segments. For example <b>...</b> tells that the text inside should be shown in boldface, while <tt>...</tt> that a monospace font should be used, and lone <br/> introduces the line break. A reader knowing some HTML will instantly recognize these tags.

Another frequent XML-like markup is used in documentation PO files, which are in many environments (like KDE or Gnome) mostly written in the Docboox XML format:

#. Tag: title
#: blackbody.docbook:13
msgid "<title>Blackbody Radiation</title>"
msgstr ""
⁠
#. Tag: para
#: geocoords.docbook:28
msgid ""
"The Equator is obviously an important part of this coordinate system; "
"it represents the <emphasis>zeropoint</emphasis> of the latitude angle, "
"and the halfway point between the poles. The Equator is the "
"<firstterm>Fundamental Plane</firstterm> of the geographic coordinate "
"system. <link linkend='ai-skycoords'>All Spherical</link> Coordinate "
"Systems define such a Fundamental Plane."
msgstr ""

The Docbook tags are named somewhat differently to the HTML-like tags from the previous example. The describe the meaning of text that they wrap, rather than the visual appearance (the so called semantic markup). But it is all the same for translator, except that knowing the meanings of text parts may be benefitial for context. Docbook tags will also sometimes provide one or few attributes following the opening tag, such as <link linkend=...> in the second message above (HTML tags may have this too).

When translating markup text, you should, in general, reproduce the same set of tags in the translation, assigning them to appropriate translated segments. Under no circumstances may the tags themselves be translated (e.g. <title> or <emphasis>), since they are processed by the computer to produce the final formatted text. As for tag attributes (linkend='ai-skycoords' in the example above), attribute names are also never translated, but in rare occasions their values in quotes may be (usually when a value is clearly a human-readable text).

However, this is not to say that you should never modify markup. Especially with HTML-like tags, not so rarely the markup in the original text is sloppy (missing closing tags), and you are free to correct it in translation. Another example would be in CJK languages^[6], where bold text is hard to read at normal font sizes, so CJK translators tend to remove <b> tags in favor of quotes. In general, the more you are familiar with the particular markup, the more you can think of doing something other than directly copying it from the original text.

Sometimes there are parts in the original text that may look somewhat like XML-like markup, but are actually not. For example:

#: utils/katecmds.cpp:180
#, kde-format
msgid "Missing argument. Usage: %1 <value>"
msgstr ""                                                                        

The <value> here is not markup, and is shown verbatim to the user. It is a placeholder, an indicator to the user that a real argument should be put in its place. For this reason, in many languages the placeholders are translated, and there is no technical problem with that. You should only exercise caution not to misjudge a tag for a placeholder. After little experience with the particular markup, the difference usually becomes obvious.

There are also non-XML like markups that tend to come up for translation. One could be the wiki markup:

#: .txt:191
msgid "=== Overlay Images ==="
msgstr ""
⁠
#: poformat.txt:193
msgid ""
"A special kind of localized image is an ''overlay image'', one which "
"does not simply replace the original, but is combined with it [...]"
msgstr ""

Here ===...=== is the approximate of <h2>...<h2> in HTML, while ''...'' is the counterpart of <i>...<i>. Another markup type is the source language for man pages, troff:

# type: Plain text
#: ../../doc/man/wesnoth.6:55
msgid ""
"compresses a savefile (B<infile>)  that is in text WML format into "
"binary WML format (B<outfile>)."
msgstr ""

where B<...> is the equivalent of <b>...<b> in HTML.

When you are faced with a new kind of markup, which you have never translated before, you should at least skim through a tutorial or two about it. This will enable you both to recognize it in the original text, and to modify it in translation if necessary.

There are a few special characters which cannot appear verbatim in the msgid or msgstr strings. Most obviously, think of the plain double quote ("): since it is used to delimit strings, a raw double quote inside the text would terminate the string prematurely, and invalidate the message syntax. Such characters are therefore written as escape sequences, a combination of the backslash (\) and another character, which is interpreted into the appropriate real character when showing the message to the user. The plain double quote is written as \":

#: kstars_i18n.cpp:3591
msgid "The \"face\" on Mars"
msgstr "\"Lice\" na Marsu"

Another frequent escaped character is the newline, presented as \n:

#: kstarsinit.cpp:699
msgid ""
"The initial position is below the horizon.\n"
"Would you like to reset to the default position?"
msgstr ""
"Početni položaj je ispod horizonta.\n"
"Želite li da vratite na podrazumevani?"

Tools that write out PO files usually unconditionally wrap the text at newlines, ignoring the specified wrap column, even when wrapping has been turned off. This is to increase readability for translator editing the PO file. If the text is not composed of markup (e.g. not Docbook), newlines are significant to the program user too, so you should carry them over into the translation. In general, unless you are confident that you can manipulate newlines in a certain way, you should follow the lead of msgid.

Another two escape sequences, usually of much lower frequency than the double quote and the newline, are the tabulator \t and the backslash itself \\ (because single backslash always starts an escape sequence). While other escape sequences are possible, they are extremely rare.

Returning to double quotes, keep in mind that while the English original usually uses plain ASCII quotes, translators tend to use "fancy" quotes according to the orthography of the language:

#: kstars_i18n.cpp:3591
msgid "The \"face\" on Mars"
msgstr "„Lice“ na Marsu"

This holds both for double and single quotes. Do check if some particular quote pairs are prescribed by the ortography of your language, and use them if they are.

In user interfaces, short texts on widgets used to perform an action or open a dialog, frequently have one letter in them underlined. This indicates that when the user presses the Alt key (on an IBM PC type keyboard) and the underlined letter together, the corresponding action will be triggered. Such letters are called accelerators, and in message strings they are usually specified by preceding them with a special character, the accelerator marker:

#: kstarsinit.cpp:163
msgid "Set Focus &Manually..."
msgstr "Zadaj fokus &ručno..."

Here the accelerator marker is the ampersand (&). Thus, the accelerator in this message will be the letter 'm' in the original text, and the letter 'r' in the translation. Accelerator markers differ across environments: ampersand is typical KDE and Qt programs, in Gnome programs it is the underscore (_), in OpenOffice the tilde (~), etc.

It may be difficult to choose accelerators in the translation (where to put the accelerator marker), because you can easily get into situations where in the same interface context (e.g. within one menu) two items end up having the same accelerator. This will not do anything too bad, e.g. the program may automatically reassign conflicting accelerators, or the user may have to press Alt and the letter several times to go through all such items. Nevertheless, it is good to avoid conflicting accelerators, but there is no definite way to do that; you can only try to track the message context in the PO file, and check the running program. This is not only the problem of translation, as not so rarely the original itself introduces conflicting accelerators.

CJK languages use input methods different to alphabetical ones (keyboard layouts), so instead of assigning an ideogram as the accelerator, they add a single Latin letter for that purpose alone:

#: kstarsinit.cpp:163
msgid "Set Focus &Manually..."
msgstr "フォーカスを手動でセット(&M)..."

This letter is usually picked to be the same as in the original text, thereby reducing the possibility of accelerator conflicts as much as the programmers were able to avoid conflicts themselves.

Accelerator does not have to be positioned at the start of a word, it can be put next to any letter or number. A reasonable order of choices would be: at the start of the most significant word in the message by default, then if it conflicts another message, at the start of another word, and if it still conflicts, inside one of the words.

The accelerator marker is usually chosen as one of the rarely used characters in normal text, but it may still appear in contexts in which it does not mark an accelerator. For example:

#: kspopupmenu.cpp:203
msgid "Center && Track"
msgstr ""
⁠
#. Tag: phrase
#: config.docbook:137
msgid "<phrase>Configure &kstars; Window</phrase>"
msgstr ""

In the first message, the accelerator marker has been used to escape itself, to produce a verbatim ampersand in output (similar as with escape sequences where double-backslash was used to represent a verbatim backslash). In the second message, the ampersand is used to insert an XML entity &kstars;. Only by context can it be concluded that the character is not used as accelerator marker, but after gaining little experience, the distinction will almost always be obvious to you.

Quite frequently English singular form will omit the number, that is, only the plural form will contain the format directive for the number:

#: modes/typesdialog.cpp:425
#, kde-format
msgid "Are you sure you want to delete this type?"
msgid_plural "Are you sure you want to delete these %1 types?"
msgstr[0] ""
msgstr[1] ""

It depends on the programming environment whether it is allowed to omit the number like this. For example, in KDE programs (kde-format flag) this is always possible, also in Gnome programs (c-format), but not in pure Qt programs (qt-format). If number omission is supported, in the translation you can either omit or retain the number in singular according to what is better for you language, and regardless of whether or not the number was omitted in the original. More precisely, you can omit the number in any plural form that is used for exactly one number. Conversely, if all forms are used for more than one number (e.g. the singular form is used for all numbers ending in digit 1), you cannot omit the number at all.

On rare occasions the plural message will have no number in the original, in either singular or plural. This happens when the programmer merely wanted to choose between the forms for "one" and "several", like this:

#: kgpg.cpp:498
msgid "Decryption of this file failed:"
msgid_plural "Decryption of these files failed:"
msgstr[0] ""
msgstr[1] ""

In such cases, in translation you should just use the same plural text for all forms but the one which is used for unity (if there is any such).

The most interesting is the third category of messages in a merged PO file. These are the old messages which were somewhat modified in the meantime, i.e. one or both of their msgctxt and msgid strings have changed. Or, this can also be a new message, but very similar to one of the old messages. There is actually no way to tell between the two, it is only by similarity to one of the old messages that a modified or new message falls into this category. Either way, such a message is called fuzzy, and looks like this:

#: src/somwidget_impl.cpp:120
#, fuzzy
#| msgid "Elements with boiling point around this temperature:"
msgid "Elements with melting point around this temperature:"
msgstr "Elementi s tačkom ključanja u blizini ove temperature:"

The fuzzy flag indicates that the message is fuzzy. The comment starting with #| is called the previous-string comment. It contains the previous value of the msgid string, for which the translation in msgstr was made. This translation is, however, not valid for the current (non-commented) msgid string. By comparing the previous and current msgid, you can see that the word "boiling" was replaced with "melting", and you can adjust the translation accordingly. Once you did that, to unfuzzy the message you should remove the fuzzy flag and previous string comments (#|), so that the final updated message is:

#: src/somwidget_impl.cpp:120
msgid "Elements with melting point around this temperature:"
msgstr "Elementi s tačkom topljenja u blizini ove temperature:"

Previous-string comments are still somewhat fresh addition to the PO format, which means that in some translation environments you will not have them in merged POs. The fuzzy message is then presented only with the fuzzy flag:

#: src/somwidget_impl.cpp:120
#, fuzzy
msgid "Elements with melting point around this temperature:"
msgstr "Elementi s tačkom ključanja u blizini ove temperature:"

It may seem that this is no great loss: so long as you are visually comparing texts, instead of comparing the previous (here missing) and current msgid, you might as well compare the current msgid and the old translation in msgstr, and adjust translation based on that. However, there are two disadvantages to this. Less importantly, it may not always be easy to spot a difference by comparing the new original and the old translation. For example, only a typo or some punctuation may have been fixed in the original, leaving you to wonder if you are missing something. More importantly, a dedicated PO editor can use the previous and current msgid to highlight differences between them, which makes it that much easier to see what has changed. Even if you are working with an ordinary text editor, there are command-line tools which can embed differences into previous msgid, again making them easier to spot. And the bigger the message, the more important to have automatic highlighting--think of a long paragraph where only one word has been changed. For these reasons, if the merged PO files you work on do not have previous-string comments, do inquire with authors if they can enable them (they may simply not know about this possibility, as it is not the default behavior on merging).

Other than msgid, the msgctxt string can also have the corresponding previous-string comment. Regardless of whether one or both of the msgctxt and msgid have been changed, both will be given in previous-string comments:

#: kstarsinit.cpp:451
#, fuzzy
#| msgctxt "Constellation Line"
#| msgid "Constell. Line"
msgctxt "Toggle Constellation Lines in the display"
msgid "Const. Lines"
msgstr "Linija sazvežđa"

In particular, a message will be fuzzied if it previously had no msgctxt and got one after merging, or had one and lost it. In the first case, the previous-string comments will contain only the msgid, although it may be the same as the current one; by this you will know that the change was only the adding of context. In the second case, the previous-string comments will contain both the msgctxt and the msgid strings, while there will be no current msgctxt. Here are two examples:

#: kstarsinit.cpp:444
#, fuzzy
#| msgid "Solar System"
msgctxt "Toggle Solar System objects in the display"
msgid "Solar System"
msgstr "Sunčev sistem"
⁠
#: finddialog.cpp:102
#, fuzzy
#| msgctxt "object name (optional)"
#| msgid "Andromeda Galaxy"
msgid "Andromeda Galaxy"
msgstr "Andromeda, galaksija"

It is important for a message to become fuzzy when only the disambiguating context is added or removed, because this has been done precisely to shed some light on the original text, which may require modifying the translation.

Fuzzy messages are a special category only from translator's viewpoint. Consumers of PO files (programs, etc.) will treat them as ordinary untranslated messages, i.e. they will use the original instead of the old translation. This is necessary, as there is no telling how inappropriate the old translation may be for the current original. The algorithm that produces fuzzy messages will sometimes turn out rather strange pairings, which to you or to the user may not look similar at all.

It is important to keep in mind that fuzzy messages are treated as untranslated. Fresh translators will sometimes manually add the fuzzy flag to a message to mark they are not entirely sure that the translation is proper, not knowing that this will totally exclude the translation from being used. Thus, you should manually add the fuzzy flag only when you are so unsure of the meaning of the message, that you explicitly want to prevent the translation from being used. This is fairly rarely needed. Instead, when you just want to mark the message so that you or someone else can check it later, you should write your doubts in a translator comment.

The last, fourth category are obsolete messages, the messages which are not present in the source any more. All obsolete messages are grouped at the end of the merged PO file, and fully commented out by the #~ comment:

#~ msgid "Set the telescope longitude and latitude."
#~ msgstr "Postavi geo. dužinu i širinu teleskopa."

Obsolete messages have no extracted comments or source references, as they are no longer present in the source. Translator comments and flags are retained, as they don't depend on the presence in the source.

It could be said that obsolete messages are in fact no messages at all, given that they do not exist from the point of consumers of the PO file, and there is nothing for translators to do with them. PO tools in general will ignore them, except to preserve them when the PO file is modified. Dedicated PO editors will invariably not show obsolete messages to the translator, and may provide an option to automatically remove them from the file on saving.

What is then the purpose of obsolete messages? It frequently happens that a section of the source content, e.g. the code around a certain feature of a program, is temporarily removed. Authors sometimes want to improve a section of the text separately, outside of the main content which is being translated, and sometimes a section is even briefly omitted by mistake when there are moves and renames in the source. When this happens, the affected messages will become obsolete in the merged PO; but, when the missing section is put back into the source, the merging algorithm will take obsolete messages into account, and promote them to real messages (either translated or fuzzy) where possible. Thus, some previous translation work may be saved.

What you should do with obsolete messages depends on the tools with which you work on PO files. For example, if you and other translators working on the given PO all use dedicated PO editors with internal storage of all previously encountered translations, the translation memory^[7], there is less need for keeping obsolete messages around, as the editor will be able to fill new messages from the memory; but there are some difficulties, as the need for translators to share the same memory. In practice, many translators choose to keep obsolete messages around for some time, and periodically (e.g. months apart) remove them from PO files. By this they achieve that accidental removals of source content, which are quickly corrected, do not bother them, while avoiding accretion of far too much obsolete material.

In light of the translation maintenance through the process of merging with templates, you can think of starting to work on a never-before translated PO file as just the "initial merging": you will have to take the template and rename it to something with the .po extension, and work from there on. What you rename it to depends on the environment, but it is usually one of two things: either the same name as that of the template but with the .po extension (like in KDE), or your language code with the .po extension (like in Gnome). This basically depends on the organization of the particular translation project.

On the other hand, sometimes for each template in the project an empty PO for your language will have been created and put in a proper place in the source tree, so that you can just start translating it when you get to it.

At any rate, when you start working on a PO file from scratch, the first thing you should do is fill out its header.

There is a number of dedicated PO editors available. They all have the same good basic support for the PO format, but each has some specialities and quirks that reflect the background of their authors. Namely, dedicated PO editors are normally written and maintained by people who are themselves engaged in certain translation projects. You should therefore try out the available editors and choose the one which is best suited to you, and possibly to the translation project within which you translate. Here is the list of some dedicated PO editors:

Some plain text editors can operate in modes, where additional editing commands became available to the user when a file of certain type is opened. Such mode for PO files is available for the following text editors: Emacs, Gedit, Vim.

apply-filter is used to pipe translation through one or several hooks (see Section 9.10, “Processing Hooks”). The hooks may modify the translation, validate it, or do something else. More precisely, the following hook types are applicable:

Parameters:

apply-header-filter is the counterpart to apply-filter to operate on headers instead of messages. Here the applicable hook types are accordingly F4B, V4B, S4B.

Parameters:

Sometimes it is possible to use simple pattern matching to discover things that should never appear in the text, such as common grammar or orthographical errors. bad-patterns can apply such patterns to translation, either as plain substring matching or regular expressions. Patterns can be given as parameters, or more conveniently, read from files.

Parameters:

check-docbook4 checks PO files extracted from Docbook 4.x files. Docbook is an XML format, typically used for documenting software.

Parameters:

Currently performed checks:

check-grammar checks translation with LanguageTool, an open source grammar and style checker (http://www.languagetool.org/). LanguageTool supports a number of languages to greater or smaller extent, which you can check on its web site.

LanguageTool can be run as standalone program or in client-server mode, and this sieve expects the latter. This means that LanguageTool has to be up and running before this sieve is run. Messages in which problems are discovered are reported to standard output.

Parameters:

check-kde4 checks PO files extracted from program code based on KDE4 library and its translation system. Note that this really means what it says; this sieve should not be used to check just any PO file which happens to be part of the KDE project (e.g. PO files covering .desktop files, pure Qt code, etc.).

Parameters:

Currently performed checks:

check-rules applies language- and project-dependent Pology validation rules to translation. See Section 8.5, “Validation Rules” for detailed discussion on writing and applying rules.

Parameters:

One or more rules can be disabled on a particular message in the PO file itself, by adding a special translator comment that starts with skip-rule: and continues with comma-separated list of rule identifiers:

# skip-rule: ruleid1, ruleid2, ...

check-spell checks spelling of translation by splitting it into words and passing them through GNU Aspell (http://aspell.net/). This sieve is a more specific counterpart to check-spell-ec, which exposes some options specific to Aspell and requires no external Python modules, only the Aspell installation. Also read Section 8.2, “Spell Checking” for details on spell-checking in Pology.

check-spell behaves mostly the same as check-spell-ec, and accepts all the same parameters with same meanings; the exception is the provider parameter, which is not present here since Aspell is the fixed provider. Only the parameters specific to this sieve are described in the following:

Aspell can be configured for use in Pology through user configuration, so that it is not necessary to issue some parameters on every run. See Section 9.2.4, “The [aspell] section”.

check-spell-ec uses the Enchant library (http://www.abisource.com/projects/enchant/) through PyEnchant Python module (http://pyenchant.sourceforge.net) to provide uniform access to different spell-checkers, such as Aspell, Ispell, Hunspell, etc. Translation is first split into words, possibly eliminating markup and other literal content, and the words are then fed to spell-checker. Messages containing unknown words are reported to standard output, with list of replacement suggestions.

Parameters:

check-spell-ec may be told to skip checking specific messages and words, and it may use internal supplemental spelling dictionaries. See Section 8.2, “Spell Checking” for these and other details on spell-checking in Pology.

Enchant can be configured for use in Pology through user configuration, so that it is not necessary to issue some parameters on every run. See Section 9.2.3, “The [enchant] section”.

The KDE Translation Project contains a great number of PO files extracted from various types of sources. This results in that for each message, there are things that the translation can, must or must not contain, for the translation to be technically valid. When run over PO files within the KDE TP, check-tp-kde will first try to determine the type of each message and then apply appropriate technical checks to it. Message type is determined based on file location, file header, message flags and contexts; even a particular message in a particular file may be checked for some very specific issue.

"Technical" issues are those which should be fixed regardless of the language and style of translation, because they can lead to loss of functionality, information or presentation to the user. For example, a technical issue would be badly paired XML tags in translation, when in the original they were well paired; a non-technical issue (and thus not checked) would be when the original ends with a certain punctuation, but translation does not -- whether such details are errors or not, depends on the target language and translation style.

For the sieve to function properly, it needs to detect the project subdirectory of each PO file up to topmost division within the branch, e.g. messages/kdebase docmessages/kdegames. This means that the local copy of the repository tree needs to follow the repository layout up to that point, e.g. kde-trunk-ui/kdebase and kde-trunk-doc/kdegames would not be valid local paths.

Parameters:

Currently available checks (keyword in parenthesis):

All markup checks can be skipped on a message by adding the no-check-markup translator flag.

PO files of The Battle of Wesnoth contain a mix of well-known and custom markup and format directives. check-tp-wesnoth heuristically determines the type of each message in a Wesnoth PO file and applies appropriate technical checks to it (where "technical" has the same meaning as in the check-tp-kde sieve).

Parameters:

Currently available checks (keyword in parenthesis):

Property maps (or pmaps for short) are one way in which arbitrary properties of language phrases can be defined for use in scripted translations, such as provided by Transcript, the translation scripting system in KDE 4.

A property map is a text file with a number of entries, each defining the properties of a certain phrase. A pmap entry starts with one or more keys and continues with arbitrary number of key-value properties. An example entry would be grammar declinations of a noun:

=/Athens/Atina/nom=Atina/gen=Atine/dat=Atini/acc=Atinu//

The first two characters define, in order, the key-value separator (here =) and the property separator (here /) for the current entry. The two separators can be any non-alphanumeric characters, and must be different. Then follows a number of entry keys, delimited by property separators, and then a number of key-value properties, each internaly delimited by the key-value separator. The entry is terminated by double property separator. Properties of an entry can be fetched in the translation scripting system by any of the entry keys; keys are case- and whitespace-insensitive.

collect-pmap will parse pmap entries from manual comments in messages, collect them, and write out a property map file. It is not necessary to explicitly specify entry keys, since the contents of msgid and msgstr are automatically added as keys. Since each manual comment is one line, it is also allowed to drop the final double separator which would normally terminate the entry. The above example would thus look like this in a PO message:

# pmap: =/nom=Atina/gen=Atine/dat=Atini/acc=Atinu/
msgctxt "Greece/city"
msgid "Athens"
msgstr "Atina"

The manual comment starts with pmap: keyword, which is followed by a normal pmap entry, except for missing keys (but additional keys can be specified when msgid and msgstr are not sufficient). It is also possible to split the entry into several comments, with only condition that all share the same set of separators:

# pmap: =/nom=Atina/gen=Atine/
# pmap: =/dat=Atini/acc=Atinu/

After collecting pmap entries from all processed PO files, if two or more entries end up having same keys, they are all removed from the collection and a warning is reported.

Pmap entries are collected only from translated, non-plural messages.

Parameters:

# pmap: =/nom=Atina/gen=Atine/dat=Atini/acc=Atinu/

# synder: Atin|a

|a: nom=a, gen=e, dat=i, acc=u

# synder: nom=Atina, gen=Atine, dat=Atini, acc=Atinu

# Full-line comment.
/key_regex_1/value_regex_1/flags # a trailing comment
/key_regex_2/value_regex_2/flags
:key_regex_3:value_regex_3:flags # different separator
# etc.

/.*/.*/

/nom|gen|dat|acc/.*/
/gender/m|f|n/
/number/s|p/

When PO files are merged with --previous option to msgmerge, fuzzy messages will retain the previous version of original text (msgctxt, msgid and msgid_plural) under #| comments. Then diff-previous can be used to embedded differences from previous to current original into previous original strings. For example, the message:

#: main.c:110
#, fuzzy
#| msgid "The Record of The Witch River"
msgid "Records of The Witch River"
msgstr "Beleška o Veštičjoj reci"

will become after sieving:

#: main.c:110
#, fuzzy
#| msgid "{-The Record-}{+Records+} of The Witch River"
msgid "Records of The Witch River"
msgstr "Beleška o Veštičjoj reci"

Text editors may even provide highlighting for the wrapped difference segments (e.g. Kwrite/Kate).

This sieve is very useful if your PO editor does not show differences in the original by itself. To be able to easily see exactly what was changed in the original is important both for efficiency and for quality. Think of a long paragraph in which only one word was changed: without a diff it will take you time to reread it, and you may even miss that changed word.

Parameters:

For every fuzzy message, empty-fuzzies removes the translation and fuzzy data (the fuzzy flag, previous strings). Translator comments are kept by default, but they can be removed as well. Obsolete fuzzy messages are completely removed.

Parameters:

equip-header-tp-kde applies the kde%header/equip-header hook to headers of PO files within the KDE Translation Project.

There are no parameters.

Ordinary ASCII quotes are easy to type on most keyboard layouts, and these quotes are frequently encountered in non-typeset English texts, rather than proper English quotes. These proper quotes are sometimes called "fancy" quotes. When translating from English, translators can thus be easily moved to use ASCII quotes themselves, instead of the fancy quotes appropriate for their language. To somewhat correct this, fancy-quote can be used to replace ASCII quotes in the translation with selected pairs of fancy quotes.

ASCII quotes that are part of text markup (e.g. attribute values in XML-like tags) must not be replaced, and this sieve will use heuristics to determine such places. In fact, it will replace quotes rather conservatively. Nevertheless, unless some sort of automatic validation is available, converted text should be manually inspected for correctness.

Parameters:

find-messages is the search and replace workhorse of Pology. It applies one or several conditions to different parts of the PO message, with selectable boolean linking between them. If the message is matched as whole, it is reported and possibly some replacements are done. Messages are by default reported to standard output, with full location reference (PO file path, line and entry number), but can also be opened directly in one of supported PO editors (see Section 9.7.1, “PO Editors”).

When used in a sieve chain, find-messages will stop further sieving of messages which did not satisfy the conditions. This makes it useful as a filter for selecting subsets of messages on which other sieves should operate.

There are three logical groups of parameters: matching parameters, replacement parameters, and general parameters. Matching and replacement parameters have certain relationships between themselves, while general parameters have mutually independent effects (i.e. as usual for sieve parameters).

$ posieve find-messages -s msgid:'foo bar'

$ posieve find-messages -s msgid:'foo bar' -s transl

$ posieve find-messages -s msgctxt:tooltip -s comment:tooltip -s or

$ posieve find-messages -s msgid:'hello' -s nmsgstr:'zdravo'

$ posieve find-messages -s fexpr:'msgid/hello/ and not msgstr/zdravo/'

$ posieve find-messages -s msgstr:foobar -s replace:fumbar

$ posieve find-messages -s msgstr:foobar -s replace:fumbar -scase
$ posieve find-messages -s msgstr:Foobar -s replace:Fumbar -scase

msgstr "... f_oobar ..."

$ posieve find-messages -s msgstr:'(f)oobar' -s replace:'\1umbar'

generate-xml creates a partial XML representation of a group of PO files.

The output XML format is as follows. Each PO file in the group is represented by a <po> element, which contains a list of <msg> elements, one for each message. The C<msg> element contains the usual parts of a PO message:

If the PO message contains plural forms, they will be represented with <plural> subelements of <msgstr>.

Parameters:

When doing corrections on a copy of PO files tree, it is not possible to easily merge back just the updated translations, because word wrapping in PO file can be different, generating much more difference than it should.

Additionally, tools like pogrep from Translate Toolkit will create new partial tree as output, containing matched messages only. merge-corr-tree will help you to merge changes made in that partial tree back into the main tree.

The main PO files tree is the input, and the pathdelta parameter is used to provide the path difference to where the partial correction tree is located.

Parameters:

normalize-header applies the normalize/canonical-header hook to PO file headers.

There are no parameters.

In older PO files, disambiguating contexts may be embedded into msgid strings, as the initial part of the string delimited from the actual text with predefined substrings, here called the "head" and the "tail". For example, in:

msgid ""
"_:this-is-context\n"
"This is original text"
msgstr "This is translated text"

the head is the underscore-colon sequence (_:), and the tail the newline (\n). normctxt-delim will convert embedded contexts of the delimiter-type to proper msgctxt strings.

Parameters:

In older PO files, disambiguating contexts may be embedded into msgid strings, as the initial part of the string separated from the actual text by a predefined substring. For example, in:

msgid "this-is-context|This is original text"
msgstr "This is translated text"

the separator string is the pipe character (|). normctxt-sep will convert embedded contexts of the separator-type to proper msgctxt strings.

Parameters:

Being translator's input, translator comments are copied verbatim to fuzzy messages created on merging with template. Depending on the purpose of translator comments (e.g. see Section 9.11, “Skipping and Selecting Checks” for some special types), it may be better to automatically remove some of them from fuzzy messages (and then possibly add them back manually when updating the translation). If run without any parameters remove-fuzzy-comments will do nothing, so one or more parameters need to be given to actually remove any comment.

Parameters:

When several removal criteria are specified, first those other than pattern and exclude are applied in unspecified order, then the pattern match, and finally the exclude match.

remove-obsolete simply removes all obsolete messages, whether fuzzy or translated, from the PO file.

There are no parameters.

remove-previous removes previous strings, i.e. #| ... comments, from messages.

Parameters:

In its default mode of operation, msgcat(1) produces an aggregate message when in different catalogs it encounters a message with the same key but different translation or translator or extracted comments. A general aggregate message looks like this:

# #-#-#-#-#  po-file-name-1 (project-version-id-1)  #-#-#-#-#
# manual-comments-1
# #-#-#-#-#  po-file-name-2 (project-version-id-2)  #-#-#-#-#
# manual-comments-2
# ...
# #-#-#-#-#  po-file-name-n (project-version-id-n)  #-#-#-#-#
# manual-comments-n
#. #-#-#-#-#  po-file-name-1 (project-version-id-1)  #-#-#-#-#
#. automatic-comments-1
#. #-#-#-#-#  po-file-name-2 (project-version-id-2)  #-#-#-#-#
#. automatic-comments-2
#. ...
#. #-#-#-#-#  po-file-name-n (project-version-id-n)  #-#-#-#-#
#. automatic-comments-n
#: source-refs-1 source-refs-2 ... source-refs-n
#, fuzzy, other-flags
msgctxt "context"
msgid "original-text"
msgstr ""
"#-#-#-#-#  po-file-name-1 (project-version-id-1)  #-#-#-#-#\n"
"translated-text-1\n"
"#-#-#-#-#  po-file-name-2 (project-version-id-2)  #-#-#-#-#\n"
"translated-text-2\n"
"..."
"#-#-#-#-#  po-file-name-n (project-version-id-n)  #-#-#-#-#\n"
"translated-text-n"

Each message part is aggregated only if different in at least one message in the group. For example, extracted comments may be aggregated while translations not.

resolve-aggregates is used to resolve aggregate messages of this kind into normal messages, by picking one variant from each aggregated part.

Parameters:

resolve-alternatives resolves alternatives directives found in the translation into one of the alternatives.

An alternative directive is a substring of the form ~@/.../.../..., for example:

msgstr "I see a ~@/pink/white/ elephant."

~@ is the directive head, which is followed by a character that defines the delimiter of alternatives (can be arbitrary), and then by alternatives themselves. The number of alternatives per directive is not defined by the directive itself, but it is provided as the sieve parameter (i.e. all alternative directives must have some number of alternatives).

Parameters:

If an alternatives directive is invalid (e.g. too little alternatives), it is reported to standard output. If at least one alternatives directive in the text is not valid, the text is not modifed.

XML entities are substrings of the form <entityname>, typically encountered in XML-like text markups, but elsewhere too. They are resolved into underlying, human-readable values at build time (when translated text documents are created) or at run time (in translated user interfaces). Sometimes it may be better to have them resolved already in the PO file itself, and that is what resolve-entities does.

Parameters:

Sometimes a PO header field or comment needs to be updated in many PO files at once, and set-header serves that purpose.

Parameters for setting and removing header fields:

Parameters for setting and removing header comments:

Note that all existing comments of given type are removed before setting the new ones, i.e. the new comments are not appended to the existing. For example, if single author parameter is issued, with a translator name and email address as value, this one translator will replace all existing translators in the header comments.

Comment values are checked for some minimal consistency, e.g. author comments must contain email addresses, licence comments the word "licence", etc.

Value strings (both of fields and comments) may contain %-directives, which are expanded to catalog-dependent substrings prior to setting the value. Currently available directive are:

If literal % character is needed (e.g. when setting the Plural-Forms field), it can be escaped by doubling it, %%. The directive can also be given inside braces, as %{...} when it would be ambiguous otherwise.

stats collects statistics on PO files, such as message and word counts, and more. Statistics can be presented in several ways and on several levels.

Parameters:

$ posieve --no-sync normctxt-sep,stats -s sep:'|' ...

$ posieve stats frobaz/
-              msg  msg/tot  w-or  w/tot-or  w-tr  ch-or  ch-tr
translated     ...    ...    ...     ...     ...    ...    ...
fuzzy          ...    ...    ...     ...     ...    ...    ...
untranslated   ...    ...    ...     ...     ...    ...    ...
total          ...    ...    ...     ...     ...    ...    ...
obsolete       ...    ...    ...     ...     ...    ...    ...

$ posieve stats -s maxwords:5 -s ondiff frobaz/
(...the statistics table...)
modifiers: at most 5 words and scaled fuzzy counts

$ posieve stats -s incomplete frobaz/
(...the overall statistics table...)
catalog              msg/f   msg/u   msg/f+u   w/f   w/u   w/f+u
frobaz/foxtrot.po        0      11        11     0   123     123
frobaz/november.po      19      14        33    85    47     132
frobaz/sierra.po        22       0        22   231     0     231

$ posieve stats -s wbar frobaz/
4572/1829/2533 w-or |¤¤¤¤¤¤¤¤¤¤¤¤¤¤¤¤¤¤¤×××××××××············|

$ posieve stats -s byfile -s msgbar frobaz/
frobaz/foxtrot.po   34/ -/11 msgs |¤¤¤¤¤¤¤¤¤¤¤¤¤¤¤·····|
frobaz/november.po  58/19/14 msgs |¤¤¤¤¤¤¤¤¤¤¤×××××····|
frobaz/sierra.po    65/22/ - msgs |¤¤¤¤¤¤¤¤¤¤¤¤¤¤××××××|
(overall)          147/41/25 msgs |¤¤¤¤¤¤¤¤¤¤¤¤¤××××···|

Some translators like to edit PO files with a plain text editor, which may provide no special support for editing PO files, other than perhaps PO syntax highlighting. In this scenario, tag-untranslated can be used to equip untranslated messages with untranslated flag, so that they can be easily looked up in the editor.

Since untranslated is not one of defined PO flags, it will be lost if the PO file is merged with the template. This is intentional: the only purpose of this flag is to facilitate immediate editing of the PO file, and you may miss to remove some of them while editing. There is no reason for untranslated flags to persist in that case. Also, if the flag is not removed after the message has been translated, a subsequent run of this sieve will remove the flag.

Parameters:

Sometimes the message is made fuzzy during merging only due to change in the msgctxt string, or its addition or removal. Some translators and languages may be less dependent on contexts than the other, or they may be in a hurry prior to the release of the translation, and then unfuzzy-context-only can be used to unfuzzy these messages in which only the context was modified. This state can be detected by comparing the current and the previous strings in the fuzzy message, i.e. the PO file must have been merged with --previous option to msgmerge.

Parameters:

unfuzzy-ctxmark-only has a similar but less wide effect compared to the unfuzzy-context-only sieve. It unfuzzies a message only if the only change that caused fuzzyness is in a specific part of msgctxt string, the UI context marker.

UI context markers are en element of KUIT markup (KDE user interface text), which state more formally the user interface context in which the text given by the PO message is used. This may be important for translation, since style guidelines will typically somewhat depend on where in the UI the text is seen. For example, there may be two messages in the code which have exactly the same text in English, but one is used as a menu item, and the other as a dialog title; with KUIT, they would be marked as:

msgctxt "@action:inmenu File"
msgid "Export as HTML"
msgstr ""
⁠
msgctxt "@title:window"
msgid "Export as HTML"
msgstr ""

The UI context marker here is the leading part of msgctxt, starting with @... and ending with first whitespace. unfuzzy-ctxmark-only will unfuzzy the message if only this marker has changed (or was added or removed), but not if the change was in the rest of the context (after the first whitespace).

Parameters:

Some text markups may have a "permissible" or "sloppy" mode, where some tags do not have to be explicitly terminated. The typical example is HTML, where <br>, <hr>, etc. do not have to be written as <br/>. (This is unlike XHTML, which is an XML instance and therefore strict in this respect.) When this permissible markup was used in the code, a programmer revisiting that code at a later time may consider it a poor style, and go about fixing it. This may cause some messages in the PO file to become fuzzy. unfuzzy-inplace-only will recognize some of these situations in a fuzzy message (by comparing the current and previous strings) and automatically modify the translation accordingly and unfuzzy the message.

There are no parameters.

PO messages obtained by conversion from Qt Linguist translation files can contain in the msgctxt an automatically extracted C++ class name, referring to the class where the message is located in the code. In the following two example messages, the C++ class name is the text before the | character:

#: ui/configdialog.cpp:50
msgctxt "Sonnet::ConfigDialog|"
msgid "Spell Checking Configuration"
msgstr ""

#: core/loader.cpp:206
#, qt-format
msgctxt "Sonnet::Loader|%1 = language name, %2 = country name"
msgid "%1 (%2)"
msgstr ""

If the programmer later changes a class name in the code, all messages inside that class will become fuzzy. The unfuzzy-qtclass-only sieve can be used to unfuzzy such messages, by verifying that the only difference between the old and the new message is in the part of msgctxt before the | character. For this to work, the PO file must have been merged with --previous option to msgmerge.

There are no parameters.

When translation on a PO file starts for the first time, or when a previously translated PO file is being updated after merging, update-header can be used to automatically set and update PO header fields to proper values. The revision date is taken as current, while other pieces of information are read from the user configuration (see Section 9.2, “User Configuration”). Note that this sieve is normally only of use when you are translating with a plain text editor, while dedicated PO editors should do this automatically when the PO file is saved after editing.

Parameters:

An example of a user configuration appropriate for this sieve would be:

[user]
name = Chusslove Illich
original-name = Часлав Илић
email = caslav.ilic@gmx.net
po-editor = Kate

[project-kde]
language = sr
language-team = Serbian
team-email = kde-i18n-sr@kde.org
plural-forms = nplurals=4; plural=n==1 ? 3 : n%%10==1 && \
               n%%100!=11 ? 0 : n%%10>=2 && n%%10<=4 && \
               (n%%100<10 || n%%100>=20) ? 1 : 2;

Note that percent characters in the plural-forms field are escaped by doubling, because single % in configuration has special meaning. Also note splitting into several lines by trailing \ (only for better looks, since configuration lines can be arbitrarily long).

In French language, some punctuation characters are separated with an unbreakable space from the preceding word. This is unlike in English, so unwary French translators sometimes miss to add the required unbreable space after or before such punctuation when translating from English. fr:setUbsp will heuristically detect such places and insert an unbreakable space.

There are no parameters.

Each translation file for a docbook in KDE has a string for documentation last update date in the format 'yyyy-mm-dd'. This sieve automatically translated those strings into Russian. The sieve uses date command in order to change date formatting. But Russian names of months are hardcoded, so that you do not need to set up Russian locale to use the sieve.

There are no parameters.

Once the word-level difference between the old and the new string has been computed, it should be somehow embedded it into the new string (or, equivalently, the old string). This can be done by wrapping removed and added text segments with {-...-} and {+...+}, respectively:

"The Record of The Witch River"

"Records of The Witch River"

"{-The Record-}{+Records+} of The Witch River"

It may happen that an opening or closing wrapper sequence occurs as a literal part of diffed strings^[11], so some method of escaping is necessary. This is done by inserting a ~ (tilde) in the middle of the literal sequence:

"Foo {+ bar"

"Foo {+ qwyx"

"Foo {~+ {-bar-}{+qwyx+}"

If strings instead contain the literal sequence {~+, then another tilde is inserted, and so on. In this way, ediff can be unambiguously resolved to old and new versions of the string. Escaping by inserting tildes also makes it easier to write a syntax higlighting definition for an editor, as the wrapper pattern is automatically broken by the tilde.

It may happen that a given string is not merely empty in the old or new PO message, but that it does not exist at all (e.g. msgctxt). For this reason it is possible to make ediff between an existing and non-existing string as well, in which case a tilde is appended to the very end of the ediff:

"a-context-note"

"{+a-context-note+}~"

Here too escaping is provided, by inserting further tildes if the ediff between two existing strings would result in a trailing tilde (if the old string is "~" and the new "foo~", the ediff is "{+foo+}~~").

It is not necessary to prescribe the exact algorithm for computing the difference between two strings. In fact, the diffing tool may allow translator to select between several diffing algorithms, depending on personal taste and situation. For example, the default algorithm of Pology's poediff does the following: words are diffed as atomic sequences, all non-word segments (punctuation, markup tags, etc.) are diffed character by character, and equal non-word segments in between two different words (e.g. whitespace) are included into the difference segment. Hence the above ediff

"{-The Record-}{+Records+} of The Witch River"

instead of the smaller

"{-The -}Record{+s+} of The Witch River"

as the former is (tentatively) easier to comprehend.

Since every difference segment in the ediff message is represented in the described way, it is sufficient to upgrade the PO syntax highlighting of an editor^[12] to indiscriminately highlight {-...-} and {+...+} segments everywhere in the message.

A PO message consists of several types of parts: strings, comments, flags, source references, etc. It would not be very constructive to diff all of them; for example, while msgstr strings should clearly be included into diffing, source references most probably should not. To avoid pondering over the advantages and disadvantages of including each and every message part, there already exists a well-defined splitting of message parts into two groups, one of which will be taken into diffing, and the other not. These two groups are:

Only extraction-invariant parts will be diffed. The working definition of which parts belong to this group is provided by what remains in obsolete messages in PO files:

Strings and translator comments are presented in the ediff message as embedded word-level differences, as described earlier. Changes in state, fuzzy and obsolete, are represented differently. A special "extracted" comment is added to the ediff message, starting with #. ediff: and listing any extra information needed to describe the ediff, including the state changes. Here is an example of two messages and the ediff they would produce^[13]:

#, fuzzy
#~| msgid "Accurate subpolar weather cycles"
#~ msgid "Accurate subpolar climate cycles"
#~ msgstr "Tačni ciklusi subpolarnog vremena"

#. ui: property (text), widget (QCheckBox, accCyclesTrop)
#: config.ui:180
#, fuzzy
#| msgid "Accurate tropical weather cycles"
msgctxt "some-superfluous-context"
msgid "Accurate tropical climate cycles"
msgstr "Tačni ciklusi tropskog vremena"

#. ediff: state {-obsolete-}
#. ui: property (text), widget (QCheckBox, accCyclesTrop)
#: config.ui:180
#, fuzzy
#| msgid "Accurate {-subpolar-}{+tropical+} weather cycles"
msgctxt "{+some-superfluous-context+}~"
msgid "Accurate {-subpolar-}{+tropical+} climate cycles"
msgstr "Tačni ciklusi {-subpolarnog-}{+tropskog+} vremena"

The first thing to note is that the ediff message contains not only the extraction-invariant parts, but also verbatim copies of extraction-prescribed parts from the new message. Effectively, the ediff is embedded into the copy of the new message. Extraction-prescribed parts are not simply discarded in order to provide more context when reviewing the diff. Here, for example, the extracted comment states that the text is a checkbox label, which may be important for the style of translation.

The other important element is the #. ediff: dummy extracted comment, which here indicates that the obsolete state has been "removed", i.e. the message was unobsoleted betwen then old and the new version of the PO file. Aside from state changes, few other indicators may be present in this comment, and they will be mentioned later on. The ediff comment is present only when necessary, if there are any indicators to show.

If diffing of two messages would always be conducted part for part, for all message parts which are taken into diffing, then in some cases the resulting ediff would not be very useful. Consider how the first example in this chapter, the line-level diff of a fuzzy and translated message, would look like as ediff if diffed part for part:

#: main.c:110
#, fuzzy
#| msgid "The Record of The Witch River"
msgid "Records of The Witch River"
msgstr "Beleška o Veštičjoj reci"

#: main.c:110
msgid "Records of The Witch River"
msgstr "Beleške o Veštičjoj reci"

#. ediff: state {-fuzzy-}
#: main.c:110
#| msgid "{-The Record of The Witch River-}~"
msgid "Records of The Witch River"
msgstr "{-Beleška-}{+Beleške+} o Veštičjoj reci"

This ediff suffers from the same problem as the line-level diff: instead of showing the difference from previous to current msgid string, the current msgid is left untouched, while the previous msgid is simply shown to have been removed.

Therefore, instead of diffing directly part for part, a special transformation takes place when exactly one of the two diffed messages is fuzzy and contains previous original strings. This splits into two directions: from fuzzy to non-fuzzy, and from non-fuzzy to fuzzy.

Diffing from a fuzzy to a non-fuzzy message is the more usual of the two directions. It typically appears when the translation has been updated after merging with template. In this case, the old and the new message are shuffled prior to diffing in the following way (*-rest denotes all diffed parts that are neither original text nor fuzzy state):

fuzzy                   -->     fuzzy
old-previous-strings    -->     old-previous-strings
old-current-strings     -->     old-previous-strings
old-rest                -->     old-rest

-                       -->     -
-                       -->     old-current-strings
new-current-strings     -->     new-current-strings
new-rest                -->     new-rest

When these shuffled messages are diffed, the resulting ediff message's current strings will show the important difference, that between the previous original text of the old (fuzzy) message and the current original text of the new (non-fuzzy) message. Ediff message's previous strings will show the less important difference between the old message's previous and current strings, but only if it is not the same as the difference between current strings. This may sound confusing, but the actual ediff produced in this way is quite intuitive:

#: main.c:110
#, fuzzy
#| msgid "The Record of The Witch River"
msgid "Records of The Witch River"
msgstr "Beleška o Veštičjoj reci"

#: main.c:110
msgid "Records of The Witch River"
msgstr "Beleške o Veštičjoj reci"

#. ediff: state {-fuzzy-}
#: main.c:110
msgid "{-The Record-}{+Records+} of The Witch River"
msgstr "{-Beleška-}{+Beleške+} o Veštičjoj reci"

From this the reviewer can see that the message was unfuzzied, the change in the original text that caused the message to become fuzzy, and what was changed in the translation to unfuzzy it. The old version of the text (in removed and equal segments) is that from the message before it got fuzzied, and the new version (in added and equal segments) is that from the message after it was unfuzzied.

The other special direction, from a non-fuzzy to a fuzzy message, should be less frequent. It appears, for example, when the diff is taken from the old, completely translated PO file, to the new PO file which has been merged with the latest template. In this case, the shuffling is as follows:

-                       -->     -
-                       -->     new-previous-strings
old-current-strings     -->     old-current-strings
old-rest                -->     old-rest

fuzzy                   -->     fuzzy
new-previous-strings    -->     new-current-strings
new-current-strings     -->     new-current-strings
new-rest                -->     new-rest

The difference in ediff messages's current strings will again be the most important one, and in previous strings the less important one and shown only if not equal to the difference in current strings. Here is what this will result in when applied one step earlier, just after merging with template:

#: main.c:89
msgid "The Record of The Witch River"
msgstr "Beleška o Veštičjoj reci"

#: main.c:110
#, fuzzy
#| msgid "The Record of The Witch River"
msgid "Records of The Witch River"
msgstr "Beleška o Veštičjoj reci"

#. ediff: state {+fuzzy+}
#: main.c:110
#, fuzzy
msgid "{-The Record-}{+Records+} of The Witch River"
msgstr "Beleška o Veštičjoj reci"

The reviewer can see that the message became fuzzy, and the change in the original text that caused that.

The diffing tool may add custom additional information at the end of any strings in the ediff message (msgid, msgstr, etc.), separated with a newline, a repeated block of one or more characters, and a newline. When this is done, the #. ediff: comment will have the infsep indicator, which states the character block used and the number of repetitions in the separator:

#. ediff: state {+fuzzy+}, infsep +- 20
#: main.c:110
#, fuzzy
msgid "{-The Record-}{+Records+} of The Witch River"
msgstr ""
"Beleška o Veštičjoj reci\n"
"+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-\n"
"some-additional-information"

Of course, the diffing tool should compute the appropriate separator such that it does not conflict with a part of the text in one of the strings. What could be this additional information? For example, it could be a filtered version of the text, to ease some special review type.

By now it was described how to make an embedded diff out of two messages, once it has been decided that those messages should be diffed. However, the translator is not expected to decide which messages to diff, but which PO files to diff. The diffing tools should then automatically pair for diffing the messages from the two PO files, and this section describes the several pairing criteria.

Most obviously, messages should be paired by key, which can be called primary pairing. The PO message key is the unique combination of msgctxt and msgid strings. In the most usual case -- reviewing an ediff from incomplete PO file with fuzzy and untranslated messages, to an updated PO file with those messages translated -- pairing by key will be fully sufficient, as both PO files will contain exactly the same set of messages. These two messages will be paired by key:

#: main.c:110
#, fuzzy
#| msgid "The Record of The Witch River"
msgid "Records of The Witch River"
msgstr "Beleška o Veštičjoj reci"

#: main.c:110
msgid "Records of The Witch River"
msgstr "Beleške o Veštičjoj reci"

But what should happen if some messages are left unpaired after pairing by key? Consider the earlier example where the diff was taken from the older fully translated to the newer merged PO file:

#: main.c:89
msgid "The Record of The Witch River"
msgstr "Beleška o Veštičjoj reci"

#: main.c:110
#, fuzzy
#| msgid "The Record of The Witch River"
msgid "Records of The Witch River"
msgstr "Beleška o Veštičjoj reci"

The keys, here just current msgid strings, of the two messages do not match, so they cannot be paired by key. Yet it would be ungainly to represent the old message as fully removed, and the new message as fully added, in the resulting ediff:

#: main.c:89
msgid "{-The Record of The Witch River-}~"
msgstr "{-Beleška o Veštičjoj reci-}~"
⁠
#. ediff: state {+fuzzy+}
#: main.c:110
#, fuzzy
#| msgid "{+The Record of The Witch River+}~"
msgid "{+Records of The Witch River+}~"
msgstr "{+Beleška o Veštičjoj reci+}~"

(That the message has been fully added or removed can be seen by trailing tilde in the msgid string, which indicates that the old or new msgid does not exist at all, and so neither the message with it.)

Instead, messages left unpaired by key should be tested for pairing by pivoting around previous strings (secondary pairing). The two messages above will thus be paired due to the fact that the current msgid of the old message is equal to the previous msgid of the new message, and will produce a single ediff message as shown earlier.

Finally, consider the third related combination, when the old PO file has not yet been merged with the template, while the new PO file has both been merged and its translation updated:

#: main.c:89
msgid "The Record of The Witch River"
msgstr "Beleška o Veštičjoj reci"

#: main.c:110
msgid "Records of The Witch River"
msgstr "Beleške o Veštičjoj reci"

Once again it would be a waste to present the old message as fully removed and the new message as fully added in the resulting ediff. When a message is left unpaired after both pairing by key and pairing by pivoting, then the two PO files can be merged in the background -- as if the new is the template for the old, and vice versa -- and then tested for chained pairing by pivoting and by key with the merged PO file as intermediary. This pairing by merging (tertiary pairing) will then produce another natural ediff:

#: main.c:110
msgid "{-The Record-}{+Records+} of The Witch River"
msgstr "{-Beleška-}{+Beleške+} o Veštičjoj reci"

It can be left to the diffing tool to decide which pairing methods beyond the primary pairing, by key, to use. There should not be much reason not to perform secondary pairing, by pivoting, as well. If tertiary pairing, by merging, is done, the user should be allowed to disable it, as it can sometimes produce strange results (subject to the fuzzy matching algorithm).

For the ediff of two PO files to also be a syntactically valid PO file, constructed ediff messages should be preceded by a PO header in output. At first glance, this PO header could be itself the ediff of headers of the PO files which were diffed. However, there are several issues with this approach:

To avert these difficulties, the following is done instead. First, a minimal valid header is constructed for the ediff PO file, independently of the headers in diffed PO files. The precise content can be left to the diffing tool, with Pology's poediff producing something like:

# +- ediff -+
msgid ""
msgstr ""
"Project-Id-Version: ediff\n"
"PO-Revision-Date: 2009-02-08 01:20+0100\n"
"Last-Translator: J. Random Translator\n"
"Language-Team: Differs\n"
"MIME-Version: 1.0\n"
"Content-Type: text/plain; charset=UTF-8\n"
"Content-Transfer-Encoding: 8bit\n"
"X-Ediff-Header-Context: ~\n"

The PO-Revision-Date header field is naturally set to the date when the ediff was made. Values for the Last-Translator and Language-Team fields can be somehow pulled from the environment (poediff will fetch them from Pology user configuration, or set some dummy values). Encoding of the ediff PO can be chosen at will, so long as all constructed ediff messages can be encoded with it (poediff will always use UTF-8). The purpose of the final, X-Ediff-Header-Context field will be explained shortly.

It is the first next entry in the ediff PO file that will actually be the ediff of headers of the two diffed PO files. Headers are diffed just like any other message, but the resulting ediff is given a few additional decorations:

# =========================================================
# Translation of The Witch River into Serbian.
# Koja Kojic <koja.kojic@nedohodnik.net>, 2008.
# {+Era Eric <era.eric@ledopad.net>, 2008.+}~
msgctxt "~"
msgid ""
"- l10n-wr/sr/wriver-main.po\n"
"+ l10n-wr/sr-mod/wriver-main.po\n"
msgstr ""
"Project-Id-Version: wriver 0.1\n"
"POT-Creation-Date: 2008-09-22 09:17+0200\n"
"PO-Revision-Date: 2008-09-{-25 20:44-}{+28 21:49+}+0100\n"
"Last-Translator: {-Koja Kojic <koja.kojic@nedohodnik-}"
"{+Era Eric <era.eric@ledopad+}.net>\n"
"Language-Team: Serbian\n"
"MIME-Version: 1.0\n"
"Content-Type: text/plain; charset=UTF-8\n"
"Content-Transfer-Encoding: 8bit\n"

Observe the usual ediff segments: translator comment with a new translator who updated the PO file has been added, and the PO-Revision-Date and Last-Translator header fields contain ediffs reflecting the update. These are the only actual differences between the two headers. More interesting are the additional decorations:

Although when a PO file is properly updated there should always be some difference in the header, it may happen that there is none. In such case, the header ediff message is still added, but it contains only the additional decorations: the visual separator comment, the special msgctxt, and the msgid with file paths. All other comments and msgstr are empty; the empty msgstr immediatelly shows that there is no difference between the headers. This "empty" header ediff is needed to provide the file paths of diffed PO files, and, if several pairs of PO files were diffed, to separate their diffs in the ediff PO file.

After the header ediff message, ordinary ediff messages follow. When all constructed ediff messages from the current pair of PO files are listed, the next pair starts with a new header ediff message, and so on.

Especially when diffing several pairs of PO files, it may happen that two ediff messages have same keys (msgid and msgctxt strings) and thus cannot be both added as such to the ediff PO file. When that happens, the ediff message which was added after the first with the same key, will have its msgctxt string padded by few random alphanumerics, to make its key unique. This padding sequence will be recorded in the #. ediff: comment, as ctxtpad field. For example:

# =========================================================
msgctxt "~"
msgid "...(first PO header ediff)..."
msgstr "..."
⁠
#. ediff: state {-fuzzy-}
msgid "White{+ horizon+}"
msgstr "Belo{+ obzorje+}"
⁠
# =========================================================
msgctxt "~"
msgid "...(second PO header ediff)..."
msgstr "..."
⁠
#. ediff: state {-fuzzy-}, ctxtpad q9ac3
msgctxt "|q9ac3~"
msgid "White{+ horizon+}"
msgstr "Belo{+ obzorje+}"

The padding sequence is appended to the original msgctxt, separated by |. If there was no original msgctxt, the padding sequence is further extended by a tilde.

When PO files are handled by a version control system (VCS), poediff can be put into VCS mode using the -c/--vcs VCS option, where the value is the keyword of one of the version control systems supported by Pology. In VCS mode, instead of giving two paths to diff, any number of version-controlled paths (files or directories) are given. Without other options, all locally modified PO files in these paths are diffed against the last commit known to local repository. For example, if a program is using a Subversion repository, then the PO files in its po/ directory can be diffed with:

$ poediff -c svn prog/po/

Specific revisions to diff can be given by the -r/--revision REV1[:REV2]. REV1 and REV2 are not necessarily direct revision IDs, but any strings that the underlying VCS can convert into revision IDs. If REV2 is omitted, diffing is preformed from REV1 to current working copy.

When ediff is made in VCS mode, msgid strings in header ediffs will state revision IDs, in <<<-separated comments next to file paths:

# =========================================================
# ...
msgctxt "~"
msgid ""
"- prog/po/sr.po <<< 20537\n"
"+ prog/po/sr.po"
msgstr "..."

Options specific to poediff:

Options common with other Pology tools:

poediff will consult the [user] section in user configuration to fill out some of the header of the ediff PO file. It also consults its own section, with the following fields avaialbe:

All ediff messages which were rejected as patches will be written out to stdin.rej.po in the current working directory if the patch was read from standard input, or to FILE.rej.po if the patch file was given by -i FILE.po option.

The file with rejected ediff messages will again be an ediff PO file. It will have the header as before, except that its comment will mention that the file contains rejects of a patching operation. Afterwards, rejected ediff messages rejected will follow. Every header ediff message will be present whether rejected or not, for the same purpose of separation and provision of file paths, but if it was not rejected as patch itself, it will be stripped of comments and msgstr string.

Furthermore, to every straigh-out rejected ediff message an ediff-no-match flag will be added. This is done, naturally, because some ediff messages may not be rejected straight-out. Consider the following scenario. A PO file has been merged to produce the fuzzy message:

#: tools/power.c:348
msgid "Active sonar low frequency"
msgstr "Niska frekvencija aktivnog sonara"

#: tools/power.c:361
#, fuzzy
#| msgid "Active sonar low frequency"
msgid "Active sonar high frequency"
msgstr "Niska frekvencija aktivnog sonara"

The translator updates the PO file, which produces the usual ediff message when going from fuzzy to translated:

#. ediff: state {-fuzzy-}
#: tools/power.c:361
msgid "Active sonar {-low-}{+high+} frequency"
msgstr "{-Niska-}{+Visoka+} frekvencija aktivnog sonara"

However, before this patch could have been applied, the programmer adds a trailing colon to the same message, and the catalog is merged again to produce:

#: tools/power.c:361
#, fuzzy
#| msgid "Active sonar low frequency"
msgid "Active sonar high frequency:"
msgstr "Niska frekvencija aktivnog sonara"

The patch cannot be cleanly applied at this point, due to the extra colon added in the meantime to the msgid, so it has to be rejected. If nothing else is done, it would appear in the file of rejects as:

#. ediff: state {-fuzzy-}
#: tools/power.c:361
#, ediff-no-match
msgid "Active sonar {-low-}{+high+} frequency"
msgstr "{-Niska-}{+Visoka+} frekvencija aktivnog sonara"

It is wastefull to reject such a near-matching patch without any indication that it could be easily adapted to the latest message in the target PO file. Therefore, when an ediff message is rejected, the following analysis is performed: by trying out message pairings as on diffing, could the old message from the patch be paired with a current message from the target PO, and that current message with the new message from the patch? Or, in other words, can an existing message in the target PO be "fitted in between" the old and new messages defined by the patch? If this is the case, instead of the original, two special ediff messages -- split rejects -- are constructed and written out: one from the old to the current message, and another from the current to the new message. They are flagged as ediff-to-cur and ediff-to-new, respectively:

#: tools/power.c:361
#, fuzzy, ediff-to-cur
#| msgid "Active sonar low frequency"
msgid "Active sonar high frequency{+:+}"
msgstr "Niska frekvencija aktivnog sonara"
⁠
#. ediff: state {-fuzzy-}
#: tools/power.c:361
#, ediff-to-new
#| msgid "Active sonar {-low-}{+high+} frequency{+:+}"
msgid "Active sonar {-low-}{+high+} frequency"
msgstr "{-Niska-}{+Visoka+} frekvencija aktivnog sonara"

There are more ways to interpret split rejects, depending on the circumstances. In this example, from the ediff-to-cur message the reviewer can see what had changed in the target message after the translator made the ediff. This can also be seen by comparing difference embedded into previous and current msgid strings in the ediff-to-new message. With a bit of editing, the reviewer can fold these two messages into an applicable patch:

#. ediff: state {-fuzzy-}
#: tools/power.c:361
#, ediff
msgid "Active sonar {-low-}{+high+} frequency:"
msgstr "{-Niska-}{+Visoka+} frekvencija aktivnog sonara:"

Since the file of rejects is also an ediff PO, after edits such as this to make some patches applicable, it can be reapplied as patch. When that is done, poepatch will silently ignore all ediff messages having ediff-no-match or ediff-to-new flags, as these have already been determined inapplicable. That is why in this example the reviewer has replaced the ediff-to-new flag with the plain ediff in the folded ediff message.

Depending on the kind of text which is being translated, and distance between the source and target language grammar, ortography, and style, it may be difficult to review the ediff in isolation. In general, messages in ediff PO file will lack positional context, which is in the full PO provided by messages immediately preceding and following the observed message. For example, a long passage from documentation probably needs no positional context. But a short, newly added message such as "Crimson" could very well need one, if it has neither msgctxt nor an extracted comment describing it: is it really a color? what grammatical ending should it have (in a language which matches adjective to noun gender)? Several messages around it in the full PO file could easily show whether it is just another color in a row, and their grammatical endings (determined by a translator earlier).

Another difficulty is when an ediff message needs some editing before being applied. This may not be easy to do this directly in the ediff PO file. Everything is fine so long as only the added text segments ({+...+}) are edited, but if the sentence needs to be restructured more thoroughly, the reviewer would have to make sure to put all additions into existing or new {+...+} segments, and to wrap all removals as {-...-} segments. If this is not carefully performed, the patch will not be applicable any more, as the old message resolved from it will no longer exactly match a message in the target PO file.

For these reasons, poepatch can apply the patch such as not to resolve the ediff, but to set all its extraction-invariant fields to the message in the target PO file. In effect, the target PO file becomes an ediff PO by itself, but only in the messages which were actually patched. To mark these messages for lookup, the usual ediff flag is added to them. For example, if the message in the patch file was:

#: title.c:274
msgid "Tutorial"
msgstr "{-Tutorijal-}{+Podučavanje+}"

then when the patch is successfully applied with embedding, the patched message in target PO file will look like this, among other messages:

#: main.c:110
msgid "Records of The Witch River"
msgstr "Beleške o Veštičjoj reci"
⁠
#: title.c:292
#, ediff
msgid "Tutorial"
msgstr "{-Tutorijal-}{+Podučavanje+}"
⁠
#: title.c:328
msgid "Start the Expedition"
msgstr "Pođi u ekspediciju"

Other than the addition of the ediff flag, note that the patched message kept its own source reference, rather than being overwritten by that from the patch. Same holds for all extraction-prescribed parts.

The reviewer can now jump over ediff flags, always having the full positional context for each patched message, and being able to edit it to heart's content, with only minimal care not to invalidate the ediff format. Wrapped difference segments can be entirely removed, non-wrapped segments can be freely edited; it should only not happen that a wrapped segment looses its opening or closing sequence. But this does not mean that the reviewer has to remove difference segments, that is, to manually unembed patched messages. poepatch can do this automatically, when run on the embedded-patched PO file with the -u/--unembed option.

A patch is applied with embedding by issuing the -e/--embed option:

$ poepatch -e <ediff.po
patched (E): foo.po

where (E) in the output indicates that the embedding is engaged. After the patched PO file had been reviewed and patched messages possibly edited, all remaining embedded differences are removed, i.e. resolved to new versions, by running:

$ poepatch -u foo.po

More precisely, only those messages having the ediff flag are resolved, therefore the reviewer must not remove them (unless manually unembedding the whole message).

What happens with rejected patches when embedding is engaged? They are also added into the target PO file, with heuristic positioning, and no separate file with rejects is created. Same as on plain patching, straight-out rejects will have the ediff-no-match flag, and split rejects ediff-to-cur or ediff-to-new. If these are not manually resolved during the review (ediff-no-match messages removed, ediff-to-* messages removed or folded), when poepatch is run to unembed the differences, it will remove all ediff-no-match and ediff-to-new messages, and resolve ediff-to-cur messages to current version.

Options specific to poepatch:

poepatch consults the following user configuration fields:

Let us assume that branches are organized by-language, that branch top directories are in the same parent directory, and that you want the summit top directory to be on the level of branch parent directory. That is:

branches/
    devel-aa/
        alpha.po
        bravo.po
        ...
    stable-aa/
        alpha.po
        bravo.po
        ...
summit-aa/
    alpha.po
    bravo.po
    ...
    summit-config

aa is the language code, which can be added for clarity, but is not necessary. It could also be a subdirectory, as in branches/devel/aa and summit/aa. At start you have the branches/ directory ready; now you create the summit-aa/ directory, and within it the summit configuration file summit-config with the following content:

S.lang = "aa"

S.summit = dict(
    topdir=S.relpath("."),
)

S.branches = [
    dict(id="devel",
         topdir=S.relpath("../branches/devel-aa")),
    dict(id="stable",
         topdir=S.relpath("../branches/stable-aa")),
    # ...and any other branches.
]

S.mappings = [
]

This is all that is necessary to set up a direct summit. The configuration file must be named exactly summit-config, because posummit will look for a file named like that through parent directories and automatically pick it up. As you may have recognized, summit-config is actually a Python source file; posummit will insert the special S object when evaluating summit-config, and it is through this object that summit options are set. S.lang states the language code of the summit. S.summit is a Python dictionary that holds options for the summit PO files (here only its location, through topdir= key), while S.branches is a list of dictionaries, each specifying options per branch (here the branch identifier by id= key and top directory). The S.relpath function is used to make file and directory paths relative to summit-config itself. S.mappings is a list of PO file mappings, for cases of splitting, mergings and renamings between branches. In this example S.mappings is set to empty only to point out its importance, but it does not need to be present if there are no mappings.

If branches are organized by-domain, the summit tree will still look the same, with PO files named by domain rather than by language:

branches/
    devel/
        alpha/
            aa.po
            bb.po
            ...
        bravo/
            aa.po
            bb.po
            ...
        ...
    stable/
        alpha/
            aa.po
            bb.po
            ...
        bravo/
            aa.po
            bb.po
            ...
        ...
summit-aa/
    alpha.po
    bravo.po
    ...
    summit-config

The only difference in the summit configuration is the addition of by_lang= keys into the branch dictionaries:

S.branches = [
    dict(id="devel",
         topdir=S.relpath("../branches/devel"),
         by_lang=S.lang),
    dict(id="stable",
         topdir=S.relpath("../branches/stable"),
         by_lang=S.lang),
]

Presence of the by_lang= key signals that the branch is organized by-domain (i.e. PO files named by language), and the value is the language code within the branch. Normaly it is set to previously defined S.lang, but it can also be something else in case different codes are used between the branches or the branches and the summit.

When the configuration file has been written, the summit can be gathered for the first time (i.e. summit PO files created):

$ cd .../summit-aa/
$ posummit gather --create

The path of each created summit PO file will be written out, along with paths of branch PO files from which messages were gathered into the summit file. After the run is finished, the summit is ready for use.

While this was sufficient to set up a summit, there is a miriyad of options available for specialized purposes, which will be presented throughout this chapter. Also, given that summit configuration file is Python code, you can add into it any scripting that you wish. Some summit options (defined through the S object) even take Python functions as values.

Again consider by-language organization of branches, similar to the direct summit example above, except that now template directories too must be present in branches:

branches/
    devel/
        aa/
            alpha.po
            bravo.po
            ...
        templates/
            alpha.pot
            bravo.pot
            ...
    stable/
        aa/
            alpha.po
            bravo.po
            ...
        templates/
            alpha.pot
            bravo.pot
            ...
summit-aa/
    alpha.po
    bravo.po
    ...
    summit-config

Here the language PO files and templates are put in subdirectories within the branch directory only for convenience, but this is not mandatory. For example, language files could reside in branches/devel-aa and templates in branches/devel-templates, no path connection is required between the two. This is because the template path per branch is explicitly given in summit-config, which would look like this:

S.lang = "aa"
S.over_templates = True

S.summit = dict(
    topdir=S.relpath("."),
)

S.branches = [
    dict(id="devel",
         topdir=S.relpath("../branches/devel/aa"),
         topdir_templates=S.relpath("../branches/devel/templates")),
    dict(id="stable",
         topdir=S.relpath("../branches/stable/aa"),
         topdir_templates=S.relpath("../branches/stable/templates")),
]

S.mappings = [
]

Compared to the configuration of a direct summit, two things are added here. S.over_templates option is set to True to indicate that summit over templates is used. The path to templates is set with topdir_templates= key for each branch.

In by-domain branch organization, the directory tree looks just the same as for direct summit, except that each domain directory also contains the templates:

branches/
    devel/
        alpha/
            aa.po
            bb.po
            ...
            alpha.pot
        bravo/
            aa.po
            bb.po
            ...
            bravo.pot
        ...
    stable/
        alpha/
            aa.po
            bb.po
            ...
            alpha.pot
        bravo/
            aa.po
            bb.po
            ...
            bravo.pot
        ...
summit-aa/
    alpha.po
    bravo.po
    ...
    summit-config

Summit configuration is modified in the same way as it was for the direct summit, by adding the by_lang= key to branch specifications:

S.branches = [
    dict(id="devel",
         topdir=S.relpath("../branches/devel/aa"),
         topdir_templates=S.relpath("../branches/devel/templates"),
         by_lang=S.lang),
    dict(id="stable",
         topdir=S.relpath("../branches/stable/aa"),
         topdir_templates=S.relpath("../branches/stable/templates"),
         by_lang=S.lang),
]

Initial gathering of the summit is done slightly differently compared to the direct summit:

$ cd .../summit-aa/
$ posummit gather --create --force

The --force option must be used here because, unlike in direct summit, explicit gathering is not regularly done in summit over dynamic templates.

As mentioned earlier, summit over static templates can be used when several language teams want to share the summit setup, for the reasons of greater efficiency. The branch directory tree looks exactly the same as in summit over dynamic templates (with several languages being present), but the summit tree is somewhat different:

branches/
    # as before, either by-language or by-domain
summit/
    summit-config-shared
    aa/
        alpha.po
        bravo.po
        ...
    bb/
        alpha.po
        bravo.po
        ...
    templates/
        alpha.pot
        bravo.pot
        ...

First of all, there is now the summit/ directory which contains subdirectories by language (the language summits) and one subdirectory for summit templates (the template summit). Then, there is no more the summit-config file, but summit-config-shared; the name can actually be anything, so long as it is not exactly summit-config. This is in order to prevent posummit from automatically picking it up, as now the configuration is not tied to a single language summit. Instead, the path to the configuration file and the language code are explicitly given as arguments to posummit.

The configuration file for by-language branches looks like this:

S.over_templates = True

S.summit = dict(
    topdir=S.relpath("%s" % S.lang),
    topdir_templates=S.relpath("templates")),
)

S.branches = [
    dict(id="devel",
         topdir=S.relpath("../branches/devel/%s" % S.lang),
         topdir_templates=S.relpath("../branches/devel/templates")),
    dict(id="stable",
         topdir=S.relpath("../branches/stable/%s" % S.lang),
         topdir_templates=S.relpath("../branches/stable/templates")),
]

S.mappings = [
]

Compared to summit over dynamic templates, here S.lang is no longer hardcoded in the configuration file, but set at each run of posummit through the command line. This means that paths of language directories too have to be dynamically adapted based on S.lang, hence the string interpolations "...%s..." % S.lang.

For by-domain branches, again simply by_lang= keys are added to branches:

S.branches = [
    dict(id="devel",
         topdir=S.relpath("../branches/devel/%s" % S.lang),
         topdir_templates=S.relpath("../branches/devel/templates"),
         by_lang=S.lang),
    dict(id="stable",
         topdir=S.relpath("../branches/stable/%s" % S.lang),
         topdir_templates=S.relpath("../branches/stable/templates"),
         by_lang=S.lang),
]

In summit over static templates mode, initital gathering is first done for summit templates, like this:

$ cd .../summit/
$ posummit summit-config-shared templates gather --create

The first two arguments are now the path to the configuration file and the language code, where templates is the dummy language code for templates^[18]. After this is finished, language summits can be gathered:

$ posummit summit-config-shared aa gather --create --force
$ posummit summit-config-shared bb gather --create --force
$ ...

Note that --force was not needed when gathering templates, because in this mode the template summit is periodically gathered, while language summits are not.

When branches contain only PO files which are used natively, by programs fetching translations at runtime, then all branch PO files will be unique by their domain name (as mandated by the Gettext runtime system). It will not happen that two branch subdirectories contain a PO file with the same name. This fits perfectly with the summit requirement that all summit PO files be unique by domain names.

However, if PO files are used as an intermediate to other formats, branches may contain same-name PO files which have otherwise nothing in common, in different subdirectories. For example, each subdirectory may contain a PO file named index.po, help.po, etc. If this would be left unattended, all the same-name PO files would be collapsed into single summit PO file, which makes no sense given that they have (almost) no common messages. For this reason, it is possible to define transformations which modify absolute branch paths during processing, such that branch PO files are seen with unique names.

Consider the following example of two branches for language aa (i.e. by-language organization) with PO files non-unique by domain name:

branches/
    devel-aa/
        chapter1/
            intro.po
            glossary.po
            ...
        chapter2/
            intro.po
            glossary.po
            ...
        ...
    stable-aa/
        chapter1/
            intro.po
            glossary.po
            ...
        chapter2/
            intro.po
            glossary.po
            ...
        ...

These branches cover some sort of a book, where each chapter has some standard elements, and thus some same-name PO files with totally different content in each chapter's subdirectory. To have unique domain names in the summit, you might decide upon a flat file tree with chapter in prefix:

summit-aa/
    chapter1-intro.po
    chapter1-glossary.po
    ...
    chapter2-intro.po
    chapter2-glossary.po
    ...
    summit-config

To achieve this, you must first write two Python functions (remember that the summit configuration file is a normal Python source file), one to split branch paths and another to join them, and add them to branch specifications in S.branches.

The function to split branch paths takes a single argument, the branch PO file path relative to the branch top directory, and returns the summit PO domain name and the summit subdirectory. For the example above, the splitting function would look like this:

def split_branch_path (subpath):
    import os
    filename = os.path.basename(subpath)      # get PO file name
    domain0 = filename[:filename.rfind(".")]  # strip .po extension
    subdir0 = os.path.dirname(subpath)        # get branch subdirectory
    domain = subdir0 + "-" + domain0          # set final domain name
    subdir = ""                               # set summit subdirectory
    return domain, subdir

Note that the branch subdirectory was used only to construct the summit domain name, while the summit subdirectory is an empty string because summit flat file tree should be flat.

The function to join branch paths takes three arguments. The first two are the summit PO domain name and the summit subdirectory. The third argument is the the value of by_lang= key for the given branch. The return value is the branch PO file path relative to the branch top directory. It would look like this:

def join_branch_path (domain, subdir, bylang):
    import os
    subdir0, domain0 = domain.split("-", 1)    # get branch domain name
                                               # and branch subdirectory
                                               # from summit domain name
    filename = domain0 + ".po"                 # branch PO file name
    subpath = os.path.join(subdir0, filename)  # branch relative path
    return subpath

Here the subdir argument (summit subdirectory) is not used is not used because it is always empty due to flat summit file tree, and bylang is not used because it is None due to by-language branch organization.

The definitions of splitting and joining functions are written into the summit-config file somewhere before the S.branches branch specification, and added to each branch through transform_path= key:

S.branches = [
    dict(id="devel",
         topdir=S.relpath("../branches/devel-aa"),
         transform_path=(split_branch_path, join_branch_path)),
    dict(id="stable",
         topdir=S.relpath("../branches/stable-aa"),
         transform_path=(split_branch_path, join_branch_path)),
]

This means that it is possible, if necessary, to define different splitting and joining functions per branch.

The usual maintenance procedure would be for one designated person (e.g. the team coordinator) to update all summit PO files and to scatter new translations to branch PO files, at certain periods of time agreed upon in the translation team.

If there are no mismatches between the branch and summit PO files, the summit update procedure is fully automatic. How the summit is updated depends on the summit mode. In direct summit, the update is performed by gathering:

$ cd $SUMMITDIR
$ posummit gather

In summit over dynamic templates, merging is performed instead:

$ cd $SUMMITDIR
$ posummit merge

Finally, in summit over static templates, first the template summit is gathered, and then language summits are merged:

$ posummit $SOMEWHERE/summit-config-shared templates gather
$ posummit $SOMEWHERE/summit-config-shared aa merge
$ posummit $SOMEWHERE/summit-config-shared bb merge
...

Note that unlike when setting up the summit, no --create or --force options are used. Without them, posummit will warn about any new mismatches between branches and the summit and abort the operation, leaving the user to examine the situation and take corrective measures. Section 5.2.3, “Handling Mismatches Between Branches and Summit” discusses this in detail.

Scattering to branches is always fully automatic. For direct summit and summit over dynamic templates it is performed with:

$ cd $SUMMITDIR
$ posummit scatter

For summit over static templates, scattering is done for each language summit:

$ posummit $SOMEWHERE/summit-config-shared aa scatter
$ posummit $SOMEWHERE/summit-config-shared bb scatter
...

If summit update (merge, gather, or both, depending on the summit mode) is scheduled to run automatically, the maintainer should make sure to be notified when posummit aborts, so that mismatches can be promptly handled.

The obvious advantage of this maintenance method is that other team members do not need to know anything about workings of the summit. They only fetch updated summit PO files, translate them, and submit them back. The disadvantage is that summit update may interfere with a particular translator who happened to be working on a PO file which just got updated in the repository, causing merge conflicts when he attempts to submit that PO file.

In this maintenance mode, each team member performs summit operations on exactly the PO files that he wants to work on. This has the advantage over centralized maintenance in that translators do not interfere in each others work, as summit PO files get updated only at the request of the translator working on it. Additionally, it may provide faster gather(-merge)-scatter turnaround time. Unfortunately, the disadvantage is that now all team members have to know how the summit is maintained, so this method is likely applicable only to strongly technical teams.

Distributed maintenance is in general the same as centralized, except that now all posummit command lines take extra arguments, namely the selection of PO files to operate on -- so called operation targets. Operation targets can be given in two ways. One is directly by file or directory paths. For example, in summit over dynamic templates mode, when working on the foobaz.po file, the translator would use the following summit commands to merge it and scatter to the branches:

$ cd $SUMMITDIR
$ posummit merge foosuite/foobaz.po
$ # ...update the translation...
$ posummit scatter foosuite/foobaz.po

To update all files in foosuite/ subdirectory at once, the translator can execute instead:

$ cd $SUMMITDIR
$ posummit merge foosuite/
$ posummit scatter foosuite/

It is also possible to single out a particular branch for scattering, by giving the path to the PO file in that branch instead of the summit. To scatter foobaz.po only to devel branch, in by-language branch organization the translator would use:

$ posummit scatter $SOMEWHERE/devel/aa/foosuite/foobaz.po

and in by-domain branch organization:

$ posummit scatter $SOMEWHERE/devel/foosuite/foobaz/po/foobaz/aa.po

Note that the current working directory still has to be within the summit directory, so that posummit can find the summit configuration file. (This requirement is not present for summit over static templates, as there the path to configuration file is given in command line.)

The other kind of operation targets are PO domain names and subdirectory names alone. In this formulation, the first example above could be replaced with:

$ posummit merge foobaz
$ posummit scatter foobaz

Since all summit PO file names are unique, this is sufficient information for posummit to know what it should operate on. To limit operation to a certain branch, the branch name is added in front of the domain names, separated by a colon. To scatter foobaz.po to devel branch:

$ posummit scatter devel:foobaz

and to scatter the complete foosuite/ subdirectory to the same branch:

$ posummit scatter devel:foosuite/

Note that trailing slash is significant here, since otherwise the argument would be interpreted as single PO file (posummit would exit with an error, reporting that such a file does not exist). Summit also has a "branch name" assigned for use in operation targets of this kind, and that is +.

When merging (or gathering in direct summit mode) is attempted, posummit may abort with the report of mismatches between branches and the summit. The translator must then make the adjustments (Section 5.2.3, “Handling Mismatches Between Branches and Summit” describes how, case by case), or report it to someone else to handle.

After selected summit and branch PO files have been updated, the translator can commit them. Alternatively, a half-distributed workflow could be used, where translators only update and commit summit PO files, while scattering to branches is centralized, and automatically performed at a given period. This makes sense because the scattering in no way interferes with translators' workflow and never needs any manual intervention.

When something changes in the PO file tree in one of the branches, posummit will by default abort gathering (or merging in summit over dynamic templates), and present a list of its findings. At this point posummit could be made to continue by issuing the --create option, but then it will resolve mismatches in a simplistic way, which will be wrong in many cases. Instead, you should examine what had happened in branches, possibly manually perform some operations on summit PO files and possibly add some branch-to-summit mappings, and rerun posummit after the necessary adjustments have been made.

Typical mismatches and their remedies are as follows: