57.1. Переводчику
Программы PostgreSQL (серверные и клиентские) могут выдавать сообщения на предпочитаемом вами языке — если эти сообщения были переведены. Создание и поддержка переведённых наборов сообщений предполагает помощь со стороны людей, которые хорошо говорят на своём языке и хотят сотрудничать с PostgreSQL. Для этого совершенно не обязательно быть программистом. В данном разделе объясняется, как можно помочь.
57.1.1. Требования
Мы не будем оценивать ваши языковые навыки — данный раздел посвящён средствам программного обеспечения. Теоретически, требуется лишь текстовый редактор. Но, скорее всего, вы захотите проверить свои переведённые сообщения. Когда вы выполняете configure, обязательно используйте параметр --enable-nls. Это также проверит библиотеку libintl и программу msgfmt, которые понадобятся всем пользователям в любом случае. Чтобы проверить свою работу, следуйте соответствующим разделам инструкций по установке.
Если вы захотите выполнить перевод или слияние каталога сообщений (описано ниже), вам понадобятся, соответственно, программы xgettext и msgmerge в GNU-совместимой реализации. Позднее, мы постараемся сделать так, что если вы будете использовать дистрибутив исходников, вам не понадобится xgettext. (При работе с Git, вам всё же это будет необходимо). В настоящее время рекомендуется GNU Gettext 0.10.36 или более поздняя версия.
К вашей реализации gettext должна прилагаться документация. Некоторая её часть, возможно, будет продублирована ниже, но более подробную информацию следует искать там.
57.1.2. Основные понятия
Пары оригинальных (английских) сообщений и их (предположительно) переведённых эквивалентов хранятся в каталогах сообщений, по одному для каждой программы (хотя связанные программы могут иметь общий каталог) и для каждого языка перевода. Существует два формата, поддерживающих каталоги сообщений: Первый — «PO» (Portable Object, переносимый объект), который является простым текстовым файлом с особым синтаксисом, редактируемый переводчиками. Второй — «MO» (Machine Object, машинный объект), который является двоичным файлом, генерируемым из соответствующего файла PO, и используется при выполнении интернационализированной программы. Переводчики не работают с файлами MO; фактически с ними едва ли кто-то работает напрямую.
Файл каталога сообщений, как можно было предположить, имеет расширение .po или .mo. Базовым именем является либо имя сопровождаемой им программы, либо язык, для которого создан файл, в зависимости от ситуации. Это создаёт некоторую путаницу. Например, psql.po (файл PO для psql) или fr.mo (файл MO на французском).
Здесь проиллюстрирован формат файлов PO:
# comment msgid "original string" msgstr "translated string" msgid "more original" msgstr "another translated" "string can be broken up like this" ...
Строки msgid извлекаются из исходного кода программы (что необязательно, но это наиболее распространённый способ). Строки msgstr изначально пусты, и переводчик заполняет их переводами. Строки могут содержать экранирующие спецсимволы в стиле С и занимать несколько строк, как в приведённом примере. (Следующая строка должна начинаться с начала строки.)
Символ # обозначает начало комментария. Если сразу за символом # следует пробел, то этим комментарием управляет переводчик. Комментарии также могут быть автоматическими, у которых сразу за # следует символ, отличный от пробела. Они управляются различными инструментами, которые работают с файлами PO и предназначены для переводчиков.
#. automatic comment #: filename.c:1023 #, flags, flags
Комментарии в стиле #. извлекаются из исходного файла, где используется сообщение. Возможно, программист вставил информацию для переводчика, например, о предполагаемом выравнивании. Комментарий #: указывает точные места, где сообщение используется в исходном коде. Переводчику не нужно смотреть на исходный код программы, но он может это сделать, если сомневается в точности перевода. Комментарии #, содержат флаги, которые некоторым образом описывают сообщение. В настоящее время существует два флага: fuzzy устанавливается, если сообщение, возможно, стало неактуально по причине изменений в исходном коде программы. Переводчик может проверить это и, возможно, удалить флаг fuzzy. Заметьте, что fuzzy сообщения недоступны конечному пользователю. Другой флаг это c-format, который указывает, что сообщение является шаблоном формата в стиле printf. Это означает, что перевод также должен быть строкой формата с таким же количеством и типом «заполнителей». Существуют средства, которые распознают и проверяют флаги c-format.
57.1.3. Создание и управление каталогами сообщений
Итак, как же создать «blank» каталог сообщений? Во-первых, зайдите в каталог, содержащий программу, сообщения которой необходимо перевести. Если имеется файл nls.mk, данная программа подготовлена к переводу.
Если уже есть некоторые .po файлы, то кто-то уже занимался переводом. Файлы получают имя language.polanguage это двухбуквенный языковой код ISO 639-1 (в нижнем регистре), например, fr.po для французского. Если требуется больше одного перевода на какой-либо язык, файлы могут также быть названы language_region.poregion это двухбуквенный код страны ISO 3166-1 (в верхнем регистре), например, pt_BR.po для португальского в Бразилии. Если найден необходимый язык, можно просто начать работать над этим файлом.
Если необходимо начать новый перевод, сначала выполните команду:
make init-po
В результате будет создан файл progname.pot.pot, чтобы отличать его от файлов PO, находящихся «в эксплуатации». T означает «шаблон».) Скопируйте данный файл в language.ponls.mk и добавляйте языковой код (или код языка и страны) к строке, которая выглядит следующим образом:
AVAIL_LANGUAGES := de fr
(Конечно, и другие языки могут появиться.)
По мере развития базовой программы или библиотеки, сообщения могут быть изменены или добавлены программистами. В этом случае нет необходимости начинать с нуля. Вместо этого выполните команду:
make update-po
что создаст новый пустой файл каталога сообщений (файл с расширением pot, с которого вы начали) и объединит его с существующими файлами PO. Если алгоритм слияния не распознаёт конкретное сообщение, он ставит пометку «fuzzy», как говорилось выше. Новый файл PO сохраняется с расширением .po.new.
57.1.4. Редактирование файлов PO
Файлы PO можно редактировать при помощи обычного текстового редактора. Переводчику нужно лишь вставить перевод между кавычками после директивы msgstr, добавить комментарии и изменить флаг fuzzy. Существует также режим PO для Emacs, который представляется довольно полезным.
Файлы PO не обязательно должны быть полностью заполнены. Программа автоматически вернётся к использованию исходной строки, если перевод недоступен (или отсутствует). Вы вполне можете предлагать для включения в исходный код неполный перевод; это даст возможность другим продолжить работу над ним. Однако после слияния рекомендуется в первую очередь удалить ненужные неточные соответствия. Помните, что неточные соответствия в итоге не будут использоваться, они могут лишь подсказывать, каким мог бы быть перевод похожей строки.
Ниже описаны моменты, которые следует учитывать при редактировании переводов:
Если оригинал заканчивается переводом строки, важно, чтобы это было отражено и в переводе. То же относится к табуляции, и т. п.
Если оригиналом является строка форматирования
printf, то перевод должен иметь такой же вид. Перевод также должен иметь те же спецификаторы формата в том же порядке. Иногда правила языка таковы, что это невозможно или как минимум нелепо. В таком случае можно модифицировать спецификаторы формата подобным образом:msgstr "Die Datei %2$s hat %1$u Zeichen."
Тогда первый заполнитель просто использует второй аргумент из списка.
digits$printf. Вы, возможно, не слышали о ней раньше, потому что она мало используется где-либо кроме интернационализации сообщений.)Если исходная строка содержит лингвистическую ошибку, сообщите об этом (или исправьте самостоятельно в исходном коде программы) и переведите правильно. Верная строка может быть добавлена, когда исходный программный код будет обновлен. Если исходная строка содержит фактическую ошибку, сообщите об этом (или исправьте самостоятельно) и не переводите её. Вместо этого, можно отметить строку, оставив комментарий в файле PO.
Сохраняйте стиль и тон исходной строки. В частности, сообщения, не являющиеся предложениями (
cannot open file %s), вероятно, не следует начинать с заглавной буквы (если в вашем языке есть разделение на регистры) или заканчивать точкой (если в вашем языке используются знаки препинания). Дополнительно см. Раздел 56.3.Если вы не знаете, что означает какое-либо сообщение, или если оно допускает двоякое толкование, обратитесь за помощью через список рассылки разработчиков. По всей вероятности, англоговорящие пользователи могут также его не понять или найти двусмысленным, поэтому лучше исправить это сообщение.
57.1. For the Translator
PostgreSQL programs (server and client) can issue their messages in your favorite language — if the messages have been translated. Creating and maintaining translated message sets needs the help of people who speak their own language well and want to contribute to the PostgreSQL effort. You do not have to be a programmer at all to do this. This section explains how to help.
57.1.1. Requirements
We won't judge your language skills — this section is about software tools. Theoretically, you only need a text editor. But this is only in the unlikely event that you do not want to try out your translated messages. When you configure your source tree, be sure to use the --enable-nls option. This will also check for the libintl library and the msgfmt program, which all end users will need anyway. To try out your work, follow the applicable portions of the installation instructions.
If you want to start a new translation effort or want to do a message catalog merge (described later), you will need the programs xgettext and msgmerge, respectively, in a GNU-compatible implementation. Later, we will try to arrange it so that if you use a packaged source distribution, you won't need xgettext. (If working from Git, you will still need it.) GNU Gettext 0.10.36 or later is currently recommended.
Your local gettext implementation should come with its own documentation. Some of that is probably duplicated in what follows, but for additional details you should look there.
57.1.2. Concepts
The pairs of original (English) messages and their (possibly) translated equivalents are kept in message catalogs, one for each program (although related programs can share a message catalog) and for each target language. There are two file formats for message catalogs: The first is the “PO” file (for Portable Object), which is a plain text file with special syntax that translators edit. The second is the “MO” file (for Machine Object), which is a binary file generated from the respective PO file and is used while the internationalized program is run. Translators do not deal with MO files; in fact hardly anyone does.
The extension of the message catalog file is to no surprise either .po or .mo. The base name is either the name of the program it accompanies, or the language the file is for, depending on the situation. This is a bit confusing. Examples are psql.po (PO file for psql) or fr.mo (MO file in French).
The file format of the PO files is illustrated here:
# comment msgid "original string" msgstr "translated string" msgid "more original" msgstr "another translated" "string can be broken up like this" ...
The msgid lines are extracted from the program source. (They need not be, but this is the most common way.) The msgstr lines are initially empty and are filled in with useful strings by the translator. The strings can contain C-style escape characters and can be continued across lines as illustrated. (The next line must start at the beginning of the line.)
The # character introduces a comment. If whitespace immediately follows the # character, then this is a comment maintained by the translator. There can also be automatic comments, which have a non-whitespace character immediately following the #. These are maintained by the various tools that operate on the PO files and are intended to aid the translator.
#. automatic comment #: filename.c:1023 #, flags, flags
The #. style comments are extracted from the source file where the message is used. Possibly the programmer has inserted information for the translator, such as about expected alignment. The #: comments indicate the exact locations where the message is used in the source. The translator need not look at the program source, but can if there is doubt about the correct translation. The #, comments contain flags that describe the message in some way. There are currently two flags: fuzzy is set if the message has possibly been outdated because of changes in the program source. The translator can then verify this and possibly remove the fuzzy flag. Note that fuzzy messages are not made available to the end user. The other flag is c-format, which indicates that the message is a printf-style format template. This means that the translation should also be a format string with the same number and type of placeholders. There are tools that can verify this, which key off the c-format flag.
57.1.3. Creating and Maintaining Message Catalogs
OK, so how does one create a “blank” message catalog? First, go into the directory that contains the program whose messages you want to translate. If there is a file nls.mk, then this program has been prepared for translation.
If there are already some .po files, then someone has already done some translation work. The files are named language.polanguage is the ISO 639-1 two-letter language code (in lower case), e.g., fr.po for French. If there is really a need for more than one translation effort per language then the files can also be named language_region.poregion is the ISO 3166-1 two-letter country code (in upper case), e.g., pt_BR.po for Portuguese in Brazil. If you find the language you wanted you can just start working on that file.
If you need to start a new translation effort, then first run the command:
make init-po
This will create a file progname.pot.pot to distinguish it from PO files that are “in production”. The T stands for “template”.) Copy this file to language.ponls.mk and add the language (or language and country) code to the line that looks like:
AVAIL_LANGUAGES := de fr
(Other languages can appear, of course.)
As the underlying program or library changes, messages might be changed or added by the programmers. In this case you do not need to start from scratch. Instead, run the command:
make update-po
which will create a new blank message catalog file (the pot file you started with) and will merge it with the existing PO files. If the merge algorithm is not sure about a particular message it marks it “fuzzy” as explained above. The new PO file is saved with a .po.new extension.
57.1.4. Editing the PO Files
The PO files can be edited with a regular text editor. The translator should only change the area between the quotes after the msgstr directive, add comments, and alter the fuzzy flag. There is (unsurprisingly) a PO mode for Emacs, which I find quite useful.
The PO files need not be completely filled in. The software will automatically fall back to the original string if no translation (or an empty translation) is available. It is no problem to submit incomplete translations for inclusions in the source tree; that gives room for other people to pick up your work. However, you are encouraged to give priority to removing fuzzy entries after doing a merge. Remember that fuzzy entries will not be installed; they only serve as reference for what might be the right translation.
Here are some things to keep in mind while editing the translations:
Make sure that if the original ends with a newline, the translation does, too. Similarly for tabs, etc.
If the original is a
printfformat string, the translation also needs to be. The translation also needs to have the same format specifiers in the same order. Sometimes the natural rules of the language make this impossible or at least awkward. In that case you can modify the format specifiers like this:msgstr "Die Datei %2$s hat %1$u Zeichen."
Then the first placeholder will actually use the second argument from the list. The
digits$printffamily of functions. You might not have heard of it before because there is little use for it outside of message internationalization.)If the original string contains a linguistic mistake, report that (or fix it yourself in the program source) and translate normally. The corrected string can be merged in when the program sources have been updated. If the original string contains a factual mistake, report that (or fix it yourself) and do not translate it. Instead, you can mark the string with a comment in the PO file.
Maintain the style and tone of the original string. Specifically, messages that are not sentences (
cannot open file %s) should probably not start with a capital letter (if your language distinguishes letter case) or end with a period (if your language uses punctuation marks). It might help to read Section 56.3.If you don't know what a message means, or if it is ambiguous, ask on the developers' mailing list. Chances are that English speaking end users might also not understand it or find it ambiguous, so it's best to improve the message.
