Re: [PATCH 0/7] Document translation with po4a.

Osamu OKANO <okano.osamu@gmail.com> writes:

Thanks for a fun read.

Do I understand correctly that this "patchset" is primarily for you to request comments on, and it is not about adding it literally as "this gives a good framework for documentation i18n and demonstrates l10n with a sample page translated to Japanese"?

I have a few comments on the overall structure.

First of all, I would prefer to have these in "po" subdirectory of Documentation.

Something like:

     Documentation/
                  /Makefile
                  /asciidoc.conf
                  /git-stash.txt
                  /po/ (new directory)
                  /po/.gitignore
                  /po/Makefile
                  /po/pot/git-stash.pot
                  /po/ja/git-stash.po
                  /po/ko/git-stash.po
                  /po/ru/git-stash.po

Then from the end-user's point of view (not from the translators), I would like to see Documentation/po/Makefile that lets me say

	cd Documentation/po && make html man install

which would first create Documentation/po/*/*.txt files using the corresponding .po files and the base documentation, and then run asciidoc to format them into Documentation/po/*/*.{html,[1-8]}, and install them to their final destination (e.g. /usr/share/man/$lang/man[1-8], but it is likely that you have to make it configurable).

When all of the above works solidly, Documentation/Makefile can learn a new rule to make "cd Documentation && make (man|html|install)" would descend to Documentation/po and run a corresponding make there.

Broadly, there are four kinds of things to keep l10n up-to-date.

 - Starting a new documentation page
   . add Documentation/po/pot/$newpage.pot for Documentation/$newpage.txt
   . commit the addition of Documentation/po/pot/$newpage.pot

 - Updating the .pot from documentation

 - Starting a new language
   . create a subdirectory in Documentation/po/$lang
   . copy Documentation/po/*.pot to Documentation/po/$lang/ and translate
   . test with the above "end-user" procedure.
   . commit the addition of Documentation/po/$lang/*.po

 - Updating an existing documentation page
   . edit Documentation/po/$lang/$page.po
   . test with the above "end-user" procedure.
   . commit the resulting Documentation/po/$lang/$page.po

 - Keeping your Documentation/po/$lang/*.pot up-to-date
   . find Documentation/po/pot/$page.pot without Documentation/po/$lang/$page.po
   . update Documentation/po/$lang/*.po from corresponding Documentation/pot/*.pot

We may want to have a rule in Documentation/po/.gitignore to ignore everything except a select few, namely Makefile, pot/*.pot, po/*/*.po, in order to avoid mistakes.

We also may want to have targets in Documentation/po/Makefile to help the translators carrying out the above set of tasks. "make lang=ja update" may do the following (just thinking aloud):

 - create Documentation/po/$(lang)/, if the directory does not exist.

 - for all Documentation/po/pot/%.pot,
   . if Documentation/po/$(lang)/%.po does not exist, copy po/pot/%.pot to
     po/$(lang)/%.po, and optionally "git add -N" the latter
   . otherwise, update po/$(lang)/%.po with po/pot/%.pot using po4a-updatepo

 - for all Documentation/po/$(lang)/%.po,
   . "git rm --cached" it if Documentation/po/pot/%.pot does not exist.

I deliberately left the management of *.pot (i.e. the first two tasks in the above list)outside the scope of "make update" run in Documentation/po/ directory. It often is easier for the i18n coordinators to manage if everybody works on translating the same version of documentation strings.

I would expect the overall project workflow to be:

 - A developer can add or modify Documentation/*.txt to document new
   commands any time without having to worry about documentation i18n.

 - A translator may tweak wording in Documentation/po/$(lang)/*.po any
   time.

 - From time to time Documentation/po/pot/*.pot files are updated from
   Documentation/*.txt by the i18n coordinator.  The translators are asked
   to update their translation when this happens.

 - A translator gets update to Documentation/po/pot/*.pot, performsn
   msgmerge^Wpo4a-updatepo to update Documentaiton/po/$(lang)/*.po and
   commits the fixed-up version.

You may want to help the i18n coordinator by supporting "make pot-update" target in Documentation/po/Makefile to be run "from time to time".