[PATCH 0/7] Document translation with po4a.

[PATCH 0/7] Document translation with po4a.

[Osamu OKANO]

1 Document translation with po4a. 
---------------------------------
I tried to translate Docmentation with po4a.
Please relive my translation flow.

1.1 prepareration 
==================
$ install po4a
$ git am 0001-Add-new-target-pot-in-Makefile.patch
$ git am 0002-add-make-shell-scripts.patch
$ cd Documentation
$ make pot    # convert .txt to .pot  with po4a-gettexize

1.2 new translation 
====================
$ mkdir ja
$ cp git-stage.pot ja/git-stage.po
  -> 0003-cp-git-stage.pot-ja-git-stage.po.patch
$ cd ja
$  translate .po by hand ...
  -> 0004-translate-ja-git-stage.po.patch
$ ../make_txt    # convert .po  to .txt  with po4a-translate
$ ../make_html   # convert .txt to .html with asciidoc

1.3 update translation 
=======================
$ git-stage.txt was updated.
  -> 0005-your-file.patch
$ cd Documentation/ja
$ ../make_update # update(merge) .po     with po4a-updatepo
  -> 0006-update-git-stage.po.patch
$ translate and remove fuzzy
  -> 0007-translate-and-remove-fazzy.patch
$ ../make_txt
$ ../make_html

=======================
Osamu OKANO (7):
  Add new target pot in Makefile
  add make(shell) scripts
  cp git-stage.pot ja/git-stage.po
  translate ja/git-stage.po
  your file
  update git-stage.po
  translate and remove fazzy

 Documentation/.gitignore      |    1 +
 Documentation/Makefile        |   15 ++++++++-
 Documentation/git-stage.txt   |    2 +-
 Documentation/ja/git-stage.po |   74 +++++++++++++++++++++++++++++++++++++++++
 Documentation/make_html       |   10 +++++
 Documentation/make_txt        |   13 +++++++
 Documentation/make_update     |   13 +++++++
 7 files changed, 126 insertions(+), 2 deletions(-)
 create mode 100644 Documentation/ja/git-stage.po
 create mode 100644 Documentation/make_html
 create mode 100644 Documentation/make_txt
 create mode 100644 Documentation/make_update

-- 
1.7.5.1.169.g505a1.dirty

[PATCH 1/7] Add new target pot in Makefile

[Osamu OKANO]

---
 Documentation/.gitignore |    1 +
 Documentation/Makefile   |   15 ++++++++++++++-
 2 files changed, 15 insertions(+), 1 deletions(-)

diff --git a/Documentation/.gitignore b/Documentation/.gitignore
index 1c3a9fe..0d8dc2e 100644
--- a/Documentation/.gitignore
+++ b/Documentation/.gitignore
@@ -3,6 +3,7 @@
 *.[1-8]
 *.made
 *.texi
+*.pot
 git.info
 gitman.info
 howto-index.txt
diff --git a/Documentation/Makefile b/Documentation/Makefile
index 36989b7..ac97d5f 100644
--- a/Documentation/Makefile
+++ b/Documentation/Makefile
@@ -11,6 +11,7 @@ MAN7_TXT=gitcli.txt gittutorial.txt gittutorial-2.txt \
 MAN_TXT = $(MAN1_TXT) $(MAN5_TXT) $(MAN7_TXT)
 MAN_XML=$(patsubst %.txt,%.xml,$(MAN_TXT))
 MAN_HTML=$(patsubst %.txt,%.html,$(MAN_TXT))
+MAN_POT=$(patsubst %.txt,%.pot,$(MAN_TXT))
 
 DOC_HTML=$(MAN_HTML)
 
@@ -41,6 +42,7 @@ man7dir=$(mandir)/man7
 # DESTDIR=
 
 ASCIIDOC=asciidoc
+PO4AG=po4a-gettextize
 ASCIIDOC_EXTRA =
 MANPAGE_XSL = manpage-normal.xsl
 XMLTO_EXTRA =
@@ -151,6 +153,7 @@ ifndef V
 	QUIET_SUBDIR0	= +@subdir=
 	QUIET_SUBDIR1	= ;$(NO_SUBDIR) echo '   ' SUBDIR $$subdir; \
 			  $(MAKE) $(PRINT_DIR) -C $$subdir
+	QUIET_PO4AG	= @echo '   ' PO4AG $@;
 	export V
 endif
 endif
@@ -166,6 +169,8 @@ man1: $(DOC_MAN1)
 man5: $(DOC_MAN5)
 man7: $(DOC_MAN7)
 
+pot: $(MAN_POT)
+
 info: git.info gitman.info
 
 pdf: user-manual.pdf
@@ -230,7 +235,7 @@ cmd-list.made: cmd-list.perl ../command-list.txt $(MAN1_TXT)
 	date >$@
 
 clean:
-	$(RM) *.xml *.xml+ *.html *.html+ *.1 *.5 *.7
+	$(RM) *.xml *.xml+ *.html *.html+ *.1 *.5 *.7 *.pot
 	$(RM) *.texi *.texi+ *.texi++ git.info gitman.info
 	$(RM) howto-index.txt howto/*.html doc.dep
 	$(RM) technical/api-*.html technical/api-index.txt
@@ -256,6 +261,14 @@ manpage-base-url.xsl: manpage-base-url.xsl.in
 		$(ASCIIDOC_EXTRA) -agit_version=$(GIT_VERSION) -o $@+ $< && \
 	mv $@+ $@
 
+%.pot : %.txt
+	$(QUIET_PO4AG)$(RM) $@+ $@ && \
+	$(PO4AG) --master-charset UTF8 --localized-charset UTF8 \
+		--master `basename $@ .pot`.txt \
+		--format text --option asciidoc \
+		--po $@+ $< && \
+	mv $@+ $@
+
 user-manual.xml: user-manual.txt user-manual.conf
 	$(QUIET_ASCIIDOC)$(RM) $@+ $@ && \
 	$(ASCIIDOC) $(ASCIIDOC_EXTRA) -b docbook -d book -o $@+ $< && \
-- 
1.7.5.1.169.g505a1.dirty

[PATCH 2/7] add make(shell) scripts

[Osamu OKANO]

---
 Documentation/make_html   |   10 ++++++++++
 Documentation/make_txt    |   13 +++++++++++++
 Documentation/make_update |   13 +++++++++++++
 3 files changed, 36 insertions(+), 0 deletions(-)
 create mode 100644 Documentation/make_html
 create mode 100644 Documentation/make_txt
 create mode 100644 Documentation/make_update

diff --git a/Documentation/make_html b/Documentation/make_html
new file mode 100644
index 0000000..cbd0a69
--- /dev/null
+++ b/Documentation/make_html
@@ -0,0 +1,10 @@
+#!/bin/sh
+for t in *.txt
+do
+  asciidoc \
+  -b xhtml11 \
+  -d manpage \
+  -f ../asciidoc.conf \
+  -o `basename $t .txt`.html \
+  $t
+done
diff --git a/Documentation/make_txt b/Documentation/make_txt
new file mode 100644
index 0000000..8fd6ab7
--- /dev/null
+++ b/Documentation/make_txt
@@ -0,0 +1,13 @@
+#!/bin/sh
+for t in *.po
+do
+  po4a-translate \
+  --keep 0 \
+  --format text \
+  --option asciidoc \
+  --master-charset UTF8 \
+  --localized-charset UTF8 \
+  --master ../`basename $t .po`.txt \
+  --po $t \
+  --localized `basename $t .po`.txt
+done
diff --git a/Documentation/make_update b/Documentation/make_update
new file mode 100644
index 0000000..59322d2
--- /dev/null
+++ b/Documentation/make_update
@@ -0,0 +1,13 @@
+#!/bin/sh
+for t in *.po
+do
+  lang=`basename $PWD`
+  cd ..
+  po4a-updatepo \
+  --master-charset UTF8 \
+  --format text \
+  --master `basename $t .po`.txt \
+  --po $lang/$t \
+  --option asciidoc
+  cd $lang
+done
-- 
1.7.5.1.169.g505a1.dirty

[PATCH 3/7] cp git-stage.pot ja/git-stage.po

[Osamu OKANO]

---
 Documentation/ja/git-stage.po |   71 +++++++++++++++++++++++++++++++++++++++++
 1 files changed, 71 insertions(+), 0 deletions(-)
 create mode 100644 Documentation/ja/git-stage.po

diff --git a/Documentation/ja/git-stage.po b/Documentation/ja/git-stage.po
new file mode 100644
index 0000000..18c057f
--- /dev/null
+++ b/Documentation/ja/git-stage.po
@@ -0,0 +1,71 @@
+# SOME DESCRIPTIVE TITLE
+# Copyright (C) YEAR Free Software Foundation, Inc.
+# This file is distributed under the same license as the PACKAGE package.
+# FIRST AUTHOR <EMAIL@ADDRESS>, YEAR.
+#
+#, fuzzy
+msgid ""
+msgstr ""
+"Project-Id-Version: PACKAGE VERSION\n"
+"POT-Creation-Date: 2011-05-13 11:06+0900\n"
+"PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n"
+"Last-Translator: FULL NAME <EMAIL@ADDRESS>\n"
+"Language-Team: LANGUAGE <LL@li.org>\n"
+"Language: \n"
+"MIME-Version: 1.0\n"
+"Content-Type: text/plain; charset=CHARSET\n"
+"Content-Transfer-Encoding: 8bit\n"
+
+#. type: Plain text
+#: git-stage.txt:2
+msgid "git-stage(1)"
+msgstr ""
+
+#. type: Title -
+#: git-stage.txt:5
+#, no-wrap
+msgid "NAME\n"
+msgstr ""
+
+#. type: delimited block =
+#: git-stage.txt:7
+msgid "git-stage - Add file contents to the staging area"
+msgstr ""
+
+#. type: Title -
+#: git-stage.txt:10
+#, no-wrap
+msgid "SYNOPSIS\n"
+msgstr ""
+
+#. type: delimited block =
+#: git-stage.txt:13
+#, no-wrap
+msgid "'git stage' args...\n"
+msgstr ""
+
+#. type: Title -
+#: git-stage.txt:16
+#, no-wrap
+msgid "DESCRIPTION\n"
+msgstr ""
+
+#. type: delimited block =
+#: git-stage.txt:20
+msgid ""
+"This is a synonym for linkgit:git-add[1].  Please refer to the documentation "
+"of that command."
+msgstr ""
+
+#. type: delimited block =
+#: git-stage.txt:22
+#, no-wrap
+msgid ""
+"GIT\n"
+"---\n"
+msgstr ""
+
+#. type: delimited block =
+#: git-stage.txt:23
+msgid "Part of the linkgit:git[1] suite"
+msgstr ""
-- 
1.7.5.1.169.g505a1.dirty

[PATCH 4/7] translate ja/git-stage.po

[Osamu OKANO]

---
 Documentation/ja/git-stage.po |   26 +++++++++++++-------------
 1 files changed, 13 insertions(+), 13 deletions(-)

diff --git a/Documentation/ja/git-stage.po b/Documentation/ja/git-stage.po
index 18c057f..e464a06 100644
--- a/Documentation/ja/git-stage.po
+++ b/Documentation/ja/git-stage.po
@@ -3,59 +3,57 @@
 # This file is distributed under the same license as the PACKAGE package.
 # FIRST AUTHOR <EMAIL@ADDRESS>, YEAR.
 #
-#, fuzzy
 msgid ""
-msgstr ""
-"Project-Id-Version: PACKAGE VERSION\n"
-"POT-Creation-Date: 2011-05-13 11:06+0900\n"
+msgstr "Project-Id-Version: PACKAGE VERSION\n"
+"POT-Creation-Date: 2011-05-12 11:34+0900\n"
 "PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n"
 "Last-Translator: FULL NAME <EMAIL@ADDRESS>\n"
 "Language-Team: LANGUAGE <LL@li.org>\n"
 "Language: \n"
 "MIME-Version: 1.0\n"
-"Content-Type: text/plain; charset=CHARSET\n"
+"Content-Type: text/plain; charset=UTF-8\n"
 "Content-Transfer-Encoding: 8bit\n"
 
 #. type: Plain text
 #: git-stage.txt:2
 msgid "git-stage(1)"
-msgstr ""
+msgstr "git-stage(1)"
 
 #. type: Title -
 #: git-stage.txt:5
 #, no-wrap
 msgid "NAME\n"
-msgstr ""
+msgstr "NAME\n"
 
 #. type: delimited block =
 #: git-stage.txt:7
 msgid "git-stage - Add file contents to the staging area"
-msgstr ""
+msgstr "git-stage - ファイルコンテンツをステージングエリアに追加する"
 
 #. type: Title -
 #: git-stage.txt:10
 #, no-wrap
 msgid "SYNOPSIS\n"
-msgstr ""
+msgstr "SYNOPSIS\n"
 
 #. type: delimited block =
 #: git-stage.txt:13
 #, no-wrap
 msgid "'git stage' args...\n"
-msgstr ""
+msgstr "'git stage' 引数...\n"
 
 #. type: Title -
 #: git-stage.txt:16
 #, no-wrap
 msgid "DESCRIPTION\n"
-msgstr ""
+msgstr "DESCRIPTION\n"
 
 #. type: delimited block =
 #: git-stage.txt:20
 msgid ""
 "This is a synonym for linkgit:git-add[1].  Please refer to the documentation "
 "of that command."
-msgstr ""
+msgstr "これは linkgit:git-add[1] の同義語です.  git-add のドキュメントを参照してください."
 
 #. type: delimited block =
 #: git-stage.txt:22
@@ -64,8 +62,10 @@ msgid ""
 "GIT\n"
 "---\n"
 msgstr ""
+"GIT\n"
+"---\n"
 
 #. type: delimited block =
 #: git-stage.txt:23
 msgid "Part of the linkgit:git[1] suite"
-msgstr ""
+msgstr "この文書は linkgit:git[1] の一部です"
-- 
1.7.5.1.169.g505a1.dirty

[PATCH 5/7] your file

[Osamu OKANO]

---
 Documentation/git-stage.txt |    2 +-
 1 files changed, 1 insertions(+), 1 deletions(-)

diff --git a/Documentation/git-stage.txt b/Documentation/git-stage.txt
index ba3fe0d..8fcb93c 100644
--- a/Documentation/git-stage.txt
+++ b/Documentation/git-stage.txt
@@ -3,7 +3,7 @@ git-stage(1)
 
 NAME
 ----
-git-stage - Add file contents to the staging area
+git-stage - Add your file contents to the staging area
 
 
 SYNOPSIS
-- 
1.7.5.1.169.g505a1.dirty

[PATCH 6/7] update git-stage.po

[Osamu OKANO]

---
 Documentation/ja/git-stage.po |   14 +++++++++-----
 1 files changed, 9 insertions(+), 5 deletions(-)

diff --git a/Documentation/ja/git-stage.po b/Documentation/ja/git-stage.po
index e464a06..697b411 100644
--- a/Documentation/ja/git-stage.po
+++ b/Documentation/ja/git-stage.po
@@ -4,15 +4,16 @@
 # FIRST AUTHOR <EMAIL@ADDRESS>, YEAR.
 #
 msgid ""
-msgstr "Project-Id-Version: PACKAGE VERSION\n"
-"POT-Creation-Date: 2011-05-12 11:34+0900\n"
+msgstr ""
+"Project-Id-Version: PACKAGE VERSION\n"
+"POT-Creation-Date: 2011-05-13 11:18+0900\n"
 "PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n"
 "Last-Translator: FULL NAME <EMAIL@ADDRESS>\n"
 "Language-Team: LANGUAGE <LL@li.org>\n"
-"Language: \n"
 "MIME-Version: 1.0\n"
 "Content-Type: text/plain; charset=UTF-8\n"
 "Content-Transfer-Encoding: 8bit\n"
+"Language: \n"
 
 #. type: Plain text
 #: git-stage.txt:2
@@ -27,7 +28,8 @@ msgstr "NAME\n"
 
 #. type: delimited block =
 #: git-stage.txt:7
-msgid "git-stage - Add file contents to the staging area"
+#, fuzzy
+msgid "git-stage - Add your file contents to the staging area"
 msgstr "git-stage - ファイルコンテンツをステージングエリアに追加する"
 
 #. type: Title -
@@ -53,7 +55,9 @@ msgstr "DESCRIPTION\n"
 msgid ""
 "This is a synonym for linkgit:git-add[1].  Please refer to the documentation "
 "of that command."
-msgstr "これは linkgit:git-add[1] の同義語です.  git-add のドキュメントを参照してください."
+msgstr ""
+"これは linkgit:git-add[1] の同義語です.  git-add のドキュメントを参照してくだ"
+"さい."
 
 #. type: delimited block =
 #: git-stage.txt:22
-- 
1.7.5.1.169.g505a1.dirty

[PATCH 7/7] translate and remove fazzy

[Osamu OKANO]

---
 Documentation/ja/git-stage.po |    3 +--
 1 files changed, 1 insertions(+), 2 deletions(-)

diff --git a/Documentation/ja/git-stage.po b/Documentation/ja/git-stage.po
index 697b411..cf45291 100644
--- a/Documentation/ja/git-stage.po
+++ b/Documentation/ja/git-stage.po
@@ -28,9 +28,8 @@ msgstr "NAME\n"
 
 #. type: delimited block =
 #: git-stage.txt:7
-#, fuzzy
 msgid "git-stage - Add your file contents to the staging area"
-msgstr "git-stage - ファイルコンテンツをステージングエリアに追加する"
+msgstr "git-stage - あなたのファイルコンテンツをステージングエリアに追加する"
 
 #. type: Title -
 #: git-stage.txt:10
-- 
1.7.5.1.169.g505a1.dirty

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

[Junio C Hamano]

Osamu OKANO <okano.osamu@gmail.com> 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".

Re: [PATCH 5/7] your file

[Junio C Hamano]

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

> ---

Why?  Sorry, this change does not make sense to me.

>  Documentation/git-stage.txt |    2 +-
>  1 files changed, 1 insertions(+), 1 deletions(-)
>
> diff --git a/Documentation/git-stage.txt b/Documentation/git-stage.txt
> index ba3fe0d..8fcb93c 100644
> --- a/Documentation/git-stage.txt
> +++ b/Documentation/git-stage.txt
> @@ -3,7 +3,7 @@ git-stage(1)
>  
>  NAME
>  ----
> -git-stage - Add file contents to the staging area
> +git-stage - Add your file contents to the staging area
>  
>  
>  SYNOPSIS

Re: [PATCH 6/7] update git-stage.po

[Junio C Hamano]

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

> @@ -53,7 +55,9 @@ msgstr "DESCRIPTION\n"
>  msgid ""
>  "This is a synonym for linkgit:git-add[1].  Please refer to the documentation "
>  "of that command."
> -msgstr "これは linkgit:git-add[1] の同義語です.  git-add のドキュメントを参照してください."
> +msgstr ""
> +"これは linkgit:git-add[1] の同義語です.  git-add のドキュメントを参照してくだ"
> +"さい."

Isn't this a no-op?  Translators need to be careful about these.

Re: [PATCH 5/7] your file

[Drew Northup]

On Fri, 2011-05-13 at 22:14 +0900, Osamu OKANO wrote:
> ---
>  Documentation/git-stage.txt |    2 +-
>  1 files changed, 1 insertions(+), 1 deletions(-)
> 
> diff --git a/Documentation/git-stage.txt b/Documentation/git-stage.txt
> index ba3fe0d..8fcb93c 100644
> --- a/Documentation/git-stage.txt
> +++ b/Documentation/git-stage.txt
> @@ -3,7 +3,7 @@ git-stage(1)
>  
>  NAME
>  ----
> -git-stage - Add file contents to the staging area
> +git-stage - Add your file contents to the staging area

Is the demarcation of file ownership (the audience) required in the
translation? I suspect that the English original was left vague on that
point for a reason (the file could be yours, his, hers, or its). If a
change in the demarcation of the audience is required in the translation
I suggest doing such changes there and leaving the source text intact as
different natural languages approach this matter differently. 
As an example, some languages require that the text be reworded
literally to: "Add the contents of the file to the staging area" as it
stands, being rather different from "Add the contents of the file
of/from [belonging to] you to the staging area"; there is advantage to
leaving this text as-is.

-- 
-Drew Northup
________________________________________________
"As opposed to vegetable or mineral error?"
-John Pescatore, SANS NewsBites Vol. 12 Num. 59

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

[Ævar Arnfjörð Bjarmason]

On Fri, May 13, 2011 at 18:48, Junio C Hamano <gitster@pobox.com> wrote:

> I have a few comments on the overall structure.

FWIW I was going to add PO support to Documentation with po4a
eventually, but I'm really glad someone beat me to it.

I agree with Junio's suggested workflow for this, it would be really
nice if you would follow up on this and submit something in that
style, I'd be happy to help if needed.

Re: [PATCH 6/7] update git-stage.po

[Osamu OKANO]

2011/5/14 Junio C Hamano <gitster@pobox.com>:
> Osamu OKANO <okano.osamu@gmail.com> writes:
>
>> @@ -53,7 +55,9 @@ msgstr "DESCRIPTION\n"
>>  msgid ""
>>  "This is a synonym for linkgit:git-add[1].  Please refer to the documentation "
>>  "of that command."
>> -msgstr "これは linkgit:git-add[1] の同義語です.  git-add のドキュメントを参照してください."
>> +msgstr ""
>> +"これは linkgit:git-add[1] の同義語です.  git-add のドキュメントを参照してくだ"
>> +"さい."
>
> Isn't this a no-op?  Translators need to be careful about these.
Yes, this part has no point.

Before I commit .po, I should run po4a-update
for the sake of line feed normalization.
Then I can avoid the crap diff.

1.2 new translation
====================
$ mkdir ja
$ cp git-stage.pot ja/git-stage.po
 -> 0003-cp-git-stage.pot-ja-git-stage.po.patch
$ cd ja
$  translate .po by hand ...
$ ../make_update  # add this procedure
 -> 0004-translate-ja-git-stage.po.patch

Re: [PATCH 6/7] update git-stage.po

[Jonathan Nieder]

Osamu OKANO wrote:
> 2011/5/14 Junio C Hamano <gitster@pobox.com>:

>> Isn't this a no-op?  Translators need to be careful about these.
>
> Yes, this part has no point.
>
> Before I commit .po, I should run po4a-update
> for the sake of line feed normalization.
> Then I can avoid the crap diff.
>
> 1.2 new translation
> ====================
> $ mkdir ja
> $ cp git-stage.pot ja/git-stage.po
>  -> 0003-cp-git-stage.pot-ja-git-stage.po.patch
> $ cd ja
> $  translate .po by hand ...
> $ ../make_update  # add this procedure
>  -> 0004-translate-ja-git-stage.po.patch

I wonder if it is possible to encode this in .gitattributes
(+ .git/config) as a "clean" filter or in .git/hooks as a pre-commit
hook, for extra safety.

Another thought I have had occasionally is that it would be nice if
the versions committed did not have line numbers while the working
copy had line numbers, so an ordinary 3-way merge could be more likely
to work for integrating changes[1].  But this second thought is less
fully cooked. :)

Jonathan

[1] This could be also done with smudge/clean filters, but it's hard
to make it fast.  Maybe a pre-commit hook combined with a variant on
the trick in v1.7.2-rc0~24^2 (autocrlf: Make it work also for
un-normalized repositories, 2010-05-12) would make it bearable.

Re: [PATCH 6/7] update git-stage.po

[Junio C Hamano]

Jonathan Nieder <jrnieder@gmail.com> writes:

> Another thought I have had occasionally is that it would be nice if
> the versions committed did not have line numbers while the working
> copy had line numbers, so an ordinary 3-way merge could be more likely
> to work for integrating changes[1].  But this second thought is less
> fully cooked. :)

I would rather see that done as a customized content-level merge backend,
i.e. at the same level as binary and union merges are specified. Losing
line number information just for the sake of the generic merge that does
not have domain knowledge (read: "stupid") is a way suboptimal solution to
the problem, I would think.

Re: [PATCH 6/7] update git-stage.po

[Jonathan Nieder]

Junio C Hamano wrote:

> I would rather see that done as a customized content-level merge backend,
> i.e. at the same level as binary and union merges are specified. Losing
> line number information just for the sake of the generic merge that does
> not have domain knowledge (read: "stupid") is a way suboptimal solution to
> the problem, I would think.

Oh!  You are definitely right.  Thank you.

Re: [PATCH 6/7] update git-stage.po

[Ævar Arnfjörð Bjarmason]

On Sat, May 14, 2011 at 21:21, Jonathan Nieder <jrnieder@gmail.com> wrote:

> Another thought I have had occasionally is that it would be nice if
> the versions committed did not have line numbers while the working
> copy had line numbers, so an ordinary 3-way merge could be more likely
> to work for integrating changes[1].  But this second thought is less
> fully cooked. :)

We went over this for the main gettext series. Not commiting the line
numbers is unworkable, because it means that users who check out
git.git can't run msgmerge, because it completely fails without line
numbers.

Having a merge strategy to deal with them would be nice, but that can
be done by using the existing gitattributes config + msgmerge(1) to do
the work.

Re: [PATCH 6/7] update git-stage.po

[Jonathan Nieder]

Ævar Arnfjörð Bjarmason wrote:

> We went over this for the main gettext series.

I mean no unkindness by this: Junio's answer was a little more
helpful.

> Having a merge strategy to deal with them would be nice, but that can
> be done by using the existing gitattributes config + msgmerge(1) to do
> the work.

Could you spell that out?  I haven't seen a working example of such
configuration before, and when I tried I wasn't able to get msgmerge
to do it.  I'd be happy to summarize the result of such an explanation
as an example for the gitattributes manpage.

Re: [PATCH 6/7] update git-stage.po

[Jonathan Nieder]

Hi again,

Ævar Arnfjörð Bjarmason wrote:

> We went over this for the main gettext series. Not commiting the line
> numbers is unworkable, because it means that users who check out
> git.git can't run msgmerge, because it completely fails without line
> numbers.

Please feel free to ignore my other reply.  You were saying something
helpful there, not just calling me out, and I completely misunderstood.

I assume you were referring to this discussion:

 http://thread.gmane.org/gmane.comp.version-control.git/147973/focus=148044

I'm confused about the msgmerge comment above.  I'll have to try it.
But anyway, of course I agree with the more important point that not
providing line numbers would make life harder for humans.

> Having a merge strategy to deal with them would be nice, but that can
> be done by using the existing gitattributes config + msgmerge(1) to do
> the work.

I'm still curious about this part, of course.

Thanks,
Jonathan

Re: [PATCH 6/7] update git-stage.po

[Ævar Arnfjörð Bjarmason]

On Sun, May 15, 2011 at 15:08, Jonathan Nieder <jrnieder@gmail.com> wrote:
> Hi again,
>
> Ævar Arnfjörð Bjarmason wrote:
>
>> We went over this for the main gettext series. Not commiting the line
>> numbers is unworkable, because it means that users who check out
>> git.git can't run msgmerge, because it completely fails without line
>> numbers.
>
> Please feel free to ignore my other reply.  You were saying something
> helpful there, not just calling me out, and I completely misunderstood.

No problem. Sorry about the terseness. I don't have a lot of time for
mailing list trawling these days.

> I assume you were referring to this discussion:
>
>  http://thread.gmane.org/gmane.comp.version-control.git/147973/focus=148044
>
> I'm confused about the msgmerge comment above.  I'll have to try it.
> But anyway, of course I agree with the more important point that not
> providing line numbers would make life harder for humans.
>
>> Having a merge strategy to deal with them would be nice, but that can
>> be done by using the existing gitattributes config + msgmerge(1) to do
>> the work.
>
> I'm still curious about this part, of course.

Maybe I'm just adding confusion here. I mean that as far as I can tell
we need to have the line numbers in the *.po files, I've been unable
to not make merges go horribly wrong without them.

Whenever I did a merge from git.pot to LANG.po where LANG.po didn't
have line numbers I ended up with issues like msgmerge confusing
strings between program A and program B, which doesn't happen if the
PO file has file:line comments.

But having them will result in merge conflicts using Git's default
merge strategy, which can be mitigated by using msgmerge(1) to resolve
the conflicts, since it knows to ignore the line numbers and to look
at the actual content.

We should be able to have a merge driver defined for git.git to do
that using the "Defining a custom merge driver" facility defined in
gitattributes(5), but I haven't actually tried to make one. But it
looks easy enough, I'll look at doing that when this becomes a problem
I have to deal with, and I'm hoping someone beats me to it :)

Re: [PATCH 6/7] update git-stage.po

[Jonathan Nieder]

Ævar Arnfjörð Bjarmason wrote:

> We should be able to have a merge driver defined for git.git to do
> that using the "Defining a custom merge driver" facility defined in
> gitattributes(5), but I haven't actually tried to make one. But it
> looks easy enough, I'll look at doing that when this becomes a problem
> I have to deal with, and I'm hoping someone beats me to it :)

Heh.  Hopefully it won't be hard to do this as a program using
libgettextpo.  For now my i18n time will be going towards playing with
the toolset you've already sent, but afterwards I'd like to try that
out.

msgmerge itself cannot perform a 3-way merge, if I understand it
correctly --- its purpose is instead to integrate new strings and
fuzzies as the document being translated changes over time, while what
I would like to do is to combine two changes to a translation without
RCS merge(1) [or rather git's ll-merge machinery] being confused by
irrelevant changes to line numbers, message order, and line wrapping.

That said, msgmerge can be helpful in almost solving the problem.

To compare old-hu.po and new-hu.po:

	msgmerge old-hu.po po/git.pot >+preimage.po
	msgmerge new-hu.po po/git.pot >+postimage.po
	git diff --no-index +preimage.po +postimage.po

To perform a 3-way merge between ancestor-hu.po, our-hu.po, and
their-hu.po:

	msgmerge ancestor-hu.po po/git.pot >+base.po
	msgmerge our-hu.po po/git.pot >+ours.po
	msgmerge their-hu.po po/git.pot >+theirs.po
	git merge-file -L ours -L base -L theirs --stdout \
		+ours.po +base.po +theirs.po >hu.po