Osamu OKANO <okano.osamu@xxxxxxxxx> writes:
> 1 Document translation with po4a.
> ---------------------------------
> I tried to translate Docmentation with po4a.
> Please relive my translation flow.
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".
--
To unsubscribe from this list: send the line "unsubscribe git" in
the body of a message to majordomo@xxxxxxxxxxxxxxx
More majordomo info at http://vger.kernel.org/majordomo-info.html