Re: [PATCH 0/7] Document translation with po4a.
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.poThen 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".
Osamu OKANO
