path: root/l10n/README

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 = csvncgi
+SUBDIRS = po csvncgi
 
-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
 csvncgi/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, csvn-ui.pot, ru_RU.utf8.po, а также обновлять
содержимое файла po/POTFILES.in.

Для корректной работы команд make, make dist необходимо наличие файлов po/LINGUAS,
po/csvn-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

обновление csvn-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 "csvn-ui"

и в данном случае, доменом по умолчанию следует считать имя 'csvn-ui'. Файл csvn-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=csvn-ui --output=po/csvn-ui.pot \
             `find -type f -name "*.c"`

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

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

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

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

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

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

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

             #. TRANSLATORS: IEC 80000-13:2008 byte
             #: csvncgi/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.

# cSvn CGI source files
csvncgi/fatal.c
csvncgi/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=csvn-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=csvn-ui.pot --output=ru_RU.utf8.po

лучше выполнять после конфигурирования исходников для того, чтобы в заголовочном коментарии
файла ru_RU.utf8.po имя пакета было задано корректно. То есть csvn-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/csvn-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 csvn-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: csvn-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.