Math Processor Unit Library

First run:
=========

До первого запуска gettextize --force каталог po/ не должен существовать!
При первом запуске gettextize --force создаются каталоги m4, po
  m4
  ├── ChangeLog
  ├── gettext.m4
  ├── iconv.m4
  ├── lib-ld.m4
  ├── lib-link.m4
  ├── lib-prefix.m4
  ├── nls.m4
  ├── po.m4
  └── progtest.m4

  po
  ├── ChangeLog
  ├── Makefile.in.in
  ├── Makevars.template
  ├── POTFILES.in
  ├── Rules-quot
  ├── boldquot.sed
  ├── en@boldquot.header
  ├── en@quot.header
  ├── insert-header.sin
  ├── quot.sed
  └── remove-potcdate.sin

скрипт ./update-gettext копирует файл po/Makevars.template в po/Makevars,
если po/Makevars не существовал, а также перезаписывает gettext.h. Кроме
того gettextize добавляет файл config.rpath, и редактирует файлы:

Makefile.am:

--- Makefile.am~	2020-10-09 02:57:21.678843280 +0300
+++ Makefile.am	2020-10-09 03:05:09.010316710 +0300
@@ -5,9 +5,9 @@
 # In build order:
 # ==============
 #
-SUBDIRS = mpu
+SUBDIRS = po mpu
 
-EXTRA_DIST = \
+EXTRA_DIST = config.rpath m4/ChangeLog  \
              config/ChangeLog config/patches bootstrap  \
              doc/README.libtool doc/autogen-examples  \
              l10n nls.h gettext.h version-tool \
              acsite.m4

configure.ac:

--- configure.ac~	2020-10-09 02:16:40.812940376 +0300
+++ configure.ac	2020-10-09 03:05:09.022316594 +0300
@@ -267,7 +267,7 @@
 dnl ============================================================
 AC_MSG_CFG_PART(OUTPUT)
 
-AC_CONFIG_FILES([
+AC_CONFIG_FILES([ po/Makefile.in
                  Makefile
                  mpu/Makefile
                  include/libmpu.h
                  mpu.pc])

После первого запуска update-gettext необходимо отдать следующие файлы
под версионный контроль:

  m4
  ├── ChangeLog
  ├── gettext.m4
  ├── iconv.m4
  ├── lib-ld.m4
  ├── lib-link.m4
  ├── lib-prefix.m4
  ├── nls.m4
  ├── po.m4
  └── progtest.m4

  po
  ├── ChangeLog
  ├── Makefile.in.in
  ├── Makevars
  ├── POTFILES.in
  ├── Rules-quot
  ├── boldquot.sed
  ├── en@boldquot.header
  ├── en@quot.header
  ├── insert-header.sin
  ├── quot.sed
  └── remove-potcdate.sin

  ABOUT-NLS
  ChangeLog
  Makefile.am
  config.rpath
  configure.ac
  gettext.h

При последующих запусках update-gettext будут обновляться файлы входящие в поставку
gettext и, при необходимости, добавляться записи в ChangeLog файлы. Как правило,
ChangeLog файлы будут обновляться только тогда, когда будет инсталлироваться новая
версия gettext.

NOTE:
---------------------------------------------------------------------------------------
В файле Makevars следует обратить внимание на переменные:

  XGETTEXT_OPTIONS = --keyword=_ --keyword=N_
  COPYRIGHT_HOLDER = Andrey V.Kosteltsev <kx@radix-linux.su>
  MSGID_BUGS_ADDRESS = Andrey V.Kosteltsev <support@radix-linux.su>
  MSGMERGE_OPTIONS = --no-wrap
  MSGINIT_OPTIONS = --no-wrap

Данные параметры надо сохранять самостоятельно перед тем как выполнять update-gettext.
---------------------------------------------------------------------------------------

Далее можно будет держать в катадоге po/ или копировать в каталог po/ с помощью
скрипта bootstrap файлы LINGUAS, libmpu.pot, ru.po, а также обновлять
содержимое файла po/POTFILES.in.

Для корректной работы команд make, make dist необходимо наличие файлов po/LINGUAS,
po/libmpu.pot, po/ru_RU.utf8.po, кроме того время последнего изменения данных файлов
должно удовлетворять зависимостям описанным в Make-файлах. То есть, если мы хотим
обновить po/POTFILES.in по окончании процедуры bootstrap, то перед конфигурированием
и сборкой необходимо обновить дату:

  $ cd po
  $ touch --touch --reference=Makefile.in.in LINGUAS POTFILES.in ru.po

Далее мы опишем все процедуры по созданию и обновлению файлов в каталоге po/
для успешной локализации продукта.


Локализация:
===========

Если первый запуск gettextize состоялся и все необходимые файлы были отданы
под версионный контроль, то последующие запуски update-gettext можно осуществлять
не беспокоясь о том, что файлы будут испорчены. Делать это нужно до вызова bootstrap
и configure.

Далее, можно заняться непосредственно локализацией продукта. Первое, что необходимо
сделать, это создать файл .pot .

В файле config.h, создаваемым скриптом configure, будет определена константа
PACKAGE, например:

/* Name of package */
#define PACKAGE "libmpu"

и в данном случае, доменом по умолчанию следует считать имя 'libmpu'. Файл libmpu.pot
можно создать следующим образом:

  $ xgettext --keyword=N_ --keyword=_ --keyword=Q_:1,2  \
             --language=C --add-comments --sort-output  \
             --default-domain=libmpu --output=po/libmpu.pot \
             `find -type f -name "*.c"`

для удобства мы создали скрипт gen-pot-file, который выполняет команду xgettext
с нужными параметрами. Его следует запускать сразу после обновления исходных
кодов программы, откуда xgettext извлекает строки для последующего перевода.

Ключевые слова N_, _, Q_:1,2 означают следующее:

  N_     - извлекаются строки типа N_("string"), которые будут присутствовать в libmpu.pot
           файле, но переводиться не будут.

  _      - извлекаются строки типа _("string"), которые будут переводиться на другие языки.

  Q_:1,2 - извлекается первая и вторая строка из конструкций типа:

             Q_("%u byte", "%u bytes", (unsigned)bytes)

           и в файле libmpu.pot будут создаваться записи подобные следующей:

             #. TRANSLATORS: IEC 80000-13:2008 byte
             #: mpu/strbuf.c:558
             #, c-format
             msgid "%u byte"
             msgid_plural "%u bytes"
             msgstr[0] ""
             msgstr[1] ""

           Таким образом с помощью ngettext() можно добиться корректного перевода числительных,
           например, 1 байт, 10 байтов, 21 байт .

Справка по --keywords здесь: https://www.gnu.org/software/gettext/manual/html_node/Default-Keywords.html

Далее необходимо обновить файл POTFILES.in, записав в него список исходных файлов, в которых
существуют строки для перевода. Сделать это можно вручную следующим образом:

# List of source files which contain translatable strings.

# libmpu source files
mpu/fatal.c
mpu/strbuf.c
. . .

Напомним, что po/POTFILES.in находится под версионным контролем.

Кроме того, под версионным контролем должен находиться файл po/LINGUAS, например,
следующего содержания:

# Set of available languages.

ru

Поскольку в файле LINGUAS присутствует сторока 'ru', в каталоге, po/
должен находиться файл po/ru.po, начальное состояние которого можно
получить с помощью утилиты msginit:

  $ cd po/
  $ msginit --no-wrap --locale=ru_RU.utf8 --input=libmpu.pot --output-file=ru.po

Утилита msginit запросит подтверждение почтового адреса:
=======================================================
The new message catalog should contain your email address, so that users can
give you feedback about the translations, and so that maintainers can contact
you in case of unexpected technical problems.

Is the following your email address?
  kx@cardhu.radix-linux.su
Please confirm by pressing Return, or enter your email address.
kx@radix-linux.su
Retrieving http://translationproject.org/team/index.html... done.
A translation team for your language (ru) does not exist yet.
If you want to create a new translation team for ru, please visit
  http://www.iro.umontreal.ca/contrib/po/HTML/teams.html
  http://www.iro.umontreal.ca/contrib/po/HTML/leaders.html
  http://www.iro.umontreal.ca/contrib/po/HTML/index.html

Created ru.po.

NOTE:
---------------------------------------------------------------------------------------
Утилита msginit не будет задавать лишних вопросов, если в файле Makevars определены
следующие переменные:

  COPYRIGHT_HOLDER = Andrey V.Kosteltsev <kx@radix-linux.su>
  MSGID_BUGS_ADDRESS = Andrey V.Kosteltsev <support@radix-linux.su>
---------------------------------------------------------------------------------------


После создания файла ru.po его можно отредактировать, обращая внимание
на следующие поля:

"Project-Id-Version: libmpu 0.0.6\n"
"Report-Msgid-Bugs-To: LibMpu Team <support@radix-linux.su>\n"
"POT-Creation-Date: 2020-10-09 09:50+0300\n"
"PO-Revision-Date: 2020-10-09 10:20+0300\n"
"Last-Translator: Andrey V.Kosteltsev <kx@radix-linux.su>\n"

Правила перевода числительных записывается на языке С и, для русского языка:

  "Plural-Forms: nplurals=3; plural=(n%10==1 && n%100!=11 ? 0 : n%10>=2 && n%10<=4 && (n%100<10 || n%100>=20) ? 1 : 2);\n"

дает:

  [0] строка
  [1] строки
  [2] строк


В дальнейшем, так как файл ru.po находится под версионным контролем,
его надо будет только обновлять.

Допустим в исходные файлы на языке С были добавлены строки, подлежащие переводу, и надо обновить
файл ru.po, чтобы в него попали новые строки. Для обновления файла ru.po, сначала
нужно обновить файл po/libmpu.pot с помощью скрипта gen-pot-file:

  $ l10n/gen-pot-file

и затем, обновить файл po/ru.po:

  $ cd po/
  $ msgmerge --no-wrap --sort-output ru.po~ ru.po > ru.po.new

Cтарый файл будет сохранен с именем po/ru.po~

NOTE:
---------------------------------------------------------------------------------------
Все указанные выше операции выполняются автоматически, с помощью скрипта gen-pot-file.
На данный момент заполнение ru.po осуществляется только для русского языка. Однако
при добавлении новых языков в файл po/LINGUAS будет легко дописать инициализацию и
заполнение (merge) строк в конец файла gen-pot-file (по образу и подобию с русским языком).
Тем более, что кодировка UTF-8 теперь используется как данность.

Утилита msginit не будет задавать лишних вопросов, если в файле Makevars определены
следующие переменные:

  COPYRIGHT_HOLDER = Andrey V.Kosteltsev <kx@radix-linux.su>
  MSGID_BUGS_ADDRESS = Andrey V.Kosteltsev <support@radix-linux.su>
---------------------------------------------------------------------------------------


Файл nls.h обеспечивает исходный код макроопределениями на случай использования gettext,
а также без использования GNU gettext, когда при конфигурировании выбирается опция:

  $ ./configure --disable-nls

Более подробную информацию об утилитах GNU gettext можно получить по адресу:

  https://www.gnu.org/software/gettext/manual/gettext.html


Enjoy.