cGit-UI for Git Repositories

Index: README
===================================================================
--- README	(nonexistent)
+++ README	(revision 5)
@@ -0,0 +1,314 @@
+
+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 = cgitcgi
++SUBDIRS = po cgitcgi
+ 
+-EXTRA_DIST = \
++EXTRA_DIST = config.rpath m4/ChangeLog  \
+              doc l10n LICENSE README.md acsite.m4 bootstrap
+
+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
+ cgitcgi/Makefile
+ Makefile
+
+После первого запуска 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.
+
+
+Далее можно будет держать в каталоге po/ или копировать в каталог po/ с помощью
+скрипта bootstrap файлы LINGUAS, cgit-ui.pot, ru_RU.utf8.po, а также обновлять
+содержимое файла po/POTFILES.in.
+
+Для корректной работы команд make, make dist необходимо наличие файлов po/LINGUAS,
+po/cgit-ui.pot, po/ru_RU.utf8.po, кроме того время последнего изменения данных файлов
+должно удовлетворять зависимостям описанным в Make-файлах. То есть, если мы хотим
+обновить po/POTFILES.in по окончании процедуры bootstrap, то перед конфигурированием
+и сборкой необходимо обновить дату:
+
+  $ cd po
+  $ touch --touch --reference=Makefile.in.in LINGUAS POTFILES.in ru_RU.utf8.po
+
+Далее мы опишем все процедуры по созданию и обновлению файлов в каталоге po/
+для успешной локализации продукта.
+
+
+Makevars
+========
+
+Прежде всего, необходимо отредактировать файл Makevars для того, чтобы при создании
+source distribution с помощью команды:
+
+  $ make dist
+
+обновление cgit-ui.pot файла, а также файлов *.po и *.gmo происходило корректно 
+
+
+Значения переменных:
+-------------------
+
+XGETTEXT_OPTIONS = --keyword=N_ --keyword=_ --keyword=Q_:1,2 \
+                   --language=C --add-comments --sort-output --no-wrap
+
+COPYRIGHT_HOLDER = Andrey V.Kosteltsev.
+
+PACKAGE_GNU = no
+
+MSGID_BUGS_ADDRESS = <support@radix.pro>
+
+MSGMERGE_OPTIONS = --update --no-wrap --sort-output --backup=simple
+
+MSGINIT_OPTIONS = --no-wrap
+
+
+
+Локализация:
+===========
+
+Если первый запуск gettextize состоялся и все необходимые файлы были отданы
+под версионный контроль, то последующие запуски update-gettext можно осуществлять
+не беспокоясь о том, что файлы будут испорчены. Делать это нужно до вызова bootstrap
+и configure.
+
+Далее, можно заняться непосредственно локализацией продукта. Первое, что необходимо
+сделать, это создать файл .pot .
+
+В файле config.h, создаваемым скриптом configure, будет определена константа
+PACKAGE, например:
+
+/* Name of package */
+#define PACKAGE "cgit-ui"
+
+и в данном случае, доменом по умолчанию следует считать имя 'cgit-ui'. Файл cgit-ui.pot
+можно создать следующим образом:
+
+  $ xgettext --keyword=N_ --keyword=_ --keyword=Q_:1,2 \
+             --language=C --add-comments --sort-output --no-wrap  \
+             --copyright-holder="Andrey V.Kosteltsev." \
+             --msgid-bugs-address="<support@radix.pro>" \
+             --default-domain=cgit-ui --output=po/cgit-ui.pot \
+             `find -type f -name "*.c"`
+
+для удобства мы создали скрипт gen-pot-file, который выполняет команду xgettext
+с нужными параметрами. Его следует запускать сразу после обновления исходных
+кодов программы, откуда xgettext извлекает строки для последующего перевода.
+
+Ключевые слова N_, _, Q_:1,2 означают следующее:
+
+  N_     - извлекаются строки типа N_("string"), которые будут присутствовать в cgit-ui.pot
+           файле, но переводиться не будут.
+
+  _      - извлекаются строки типа _("string"), которые будут переводиться на другие языки.
+
+  Q_:1,2 - извлекается первая и вторая строка из конструкций типа:
+
+             Q_("%u byte", "%u bytes", (unsigned)bytes)
+
+           и в файле cgit-ui.pot будут создаваться записи подобные следующей:
+
+             #. TRANSLATORS: IEC 80000-13:2008 byte
+             #: cgitcgi/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.
+
+# cGit CGI source files
+cgitcgi/fatal.c
+cgitcgi/strbuf.c
+. . .
+
+Напомним, что po/POTFILES.in находится под версионным контролем.
+
+Кроме того, под версионным контролем должен находиться файл po/LINGUAS, например,
+следующего содержания:
+
+# Set of available languages.
+
+ru_RU.utf8
+
+Поскольку в файле LINGUAS присутствует сторока 'ru_RU.utf8', в каталоге, po/
+должен находиться файл po/ru_RU.utf8.po, начальное состояние которого можно
+получить с помощью утилиты msginit:
+
+  $ cd po/
+  $ msginit --no-wrap --locale=ru_RU.utf8 --input=cgit-ui.pot --output=ru_RU.utf8.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.pro
+Please confirm by pressing Return, or enter your email address.
+kx@radix.pro
+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_RU.utf8.po.
+
+Создание файла ru_RU.utf8.po с помощью команды
+
+  $ msginit --no-wrap --locale=ru_RU.utf8 --input=cgit-ui.pot --output=ru_RU.utf8.po
+
+лучше выполнять после конфигурирования исходников для того, чтобы в заголовочном коментарии
+файла ru_RU.utf8.po имя пакета было задано корректно. То есть cgit-ui по имени PACKAGE.
+
+
+Правила перевода числительных записывается на языке С и, для русского языка:
+
+  "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_RU.utf8.po находится под версионным контролем,
+его надо будет только обновлять.
+
+Допустим в исходные файлы на языке С были добавлены строки, подлежащие переводу, и надо обновить
+файл ru_RU.utf8.po, чтобы в него попали новые строки. Для обновления файла ru_RU.utf8.po, сначала
+нужно обновить файл po/cgit-ui.pot с помощью скрипта gen-pot-file:
+
+  $ l10n/gen-pot-file
+
+и затем, обновить файл po/ru_RU.utf8.po:
+
+  $ cd po/
+  $ msgmerge --update --no-wrap --sort-output --backup=simple ru_RU.utf8.po cgit-ui.pot
+
+Cтарый файл будет сохранен с именем po/ru_RU.utf8.po~
+
+
+Таким образом для обновления как самой утилиты gettext, так и файлов локализации, следует
+(в корне исходного пакета программ) вызывать процедуры обновления в следующем порядке:
+
+  $ ./l10n/update-gettext
+  $ ./l10n/gen-pot-file
+  $ ./l10n/merge-ru_RU.utf8-messages
+
+Остается только не забывать добавлять новые файлы в po/POTFILES.in, а при добавлении новых
+языков (локалей), дополнять файл po/LINGUAS. И наконец еще одно замечание. В файлах *.po,
+при обновлении номера версии продукта, строку:
+
+"Project-Id-Version: cgit-ui 0.0.6\n"
+
+надо обновлять вручную (разумеется если .po файл уже существует под версионным контролем,
+а не создается вновь с помощью утилиты msginit).
+
+
+Файл nls.h обеспечивает исходный код макроопределениями на случай использования gettext,
+а также без использования GNU gettext, когда при конфигурировании выбирается опция:
+
+  $ ./configure --disable-nls
+
+Более подробную информацию об утилитах GNU gettext можно получить по адресу:
+
+  https://www.gnu.org/software/gettext/manual/gettext.html
+
+
+Enjoy.