[WIP]: localize guix.texi

[WIP]: localize guix.texi

[Julien Lepiller]

Hi,

here is my first attempt at localizing guix.texi. This patch adds
guix.fr.texi, a localized version of the manual. It uses po4a to
generate the .po file and use that same file to generate the localized
manual.

I had to include the guix.fr.texi in the commit because it is necessary
that it exists in order to add it to info_TEXINFOS. This means that
this version of guix now requires po4a and will always build the
localized manuals in every available language. I don't really like that
though.

I had to add a rule in Makefile.am without which guix.fr.info wouldn't
be built. Similar rules are required for generating the html and pdf
versions.

thoughts?

Re: [WIP]: localize guix.texi

[Julien Lepiller]

[-- Attachment #1: Type: text/plain, Size: 912 bytes --]

Le Mon, 19 Feb 2018 23:34:37 +0100,
Julien Lepiller <julien@lepiller.eu> a écrit :

> Hi,
> 
> here is my first attempt at localizing guix.texi. This patch adds
> guix.fr.texi, a localized version of the manual. It uses po4a to
> generate the .po file and use that same file to generate the localized
> manual.
> 
> I had to include the guix.fr.texi in the commit because it is
> necessary that it exists in order to add it to info_TEXINFOS. This
> means that this version of guix now requires po4a and will always
> build the localized manuals in every available language. I don't
> really like that though.
> 
> I had to add a rule in Makefile.am without which guix.fr.info wouldn't
> be built. Similar rules are required for generating the html and pdf
> versions.
> 
> thoughts?

I forgot the patch, here it is. I removed guix.fr.texi and fr.po from
the patch as they are ~1MB each.

[-- Warning: decoded text below may be mangled, UTF-8 assumed --]
[-- Attachment #2: 0001-doc-Allow-documentation-to-be-translated.patch --]
[-- Type: text/x-patch, Size: 4148 bytes --]

From 7443ce7407a7194a9d9487f95f940b4b9adf5d82 Mon Sep 17 00:00:00 2001
From: Julien Lepiller <julien@lepiller.eu>
Date: Mon, 19 Feb 2018 23:24:30 +0100
Subject: [PATCH] doc: Allow documentation to be translated.

po/doc/local.mk: New file.
Makefile.am: Include it.
doc/local.mk (info_TEXINFOS, BUILT_SOURCES, EXTRA_DIST, MAINTAINERCLEANFILES):
Add guix.fr.texi
(rules): New rule to build localized texi files
.gitignore: Ignore doc/version.*.texi
---
 .gitignore      |  1 +
 Makefile.am     |  3 +++
 doc/local.mk    | 21 +++++++++++++++++----
 po/doc/local.mk | 23 +++++++++++++++++++++++
 4 files changed, 44 insertions(+), 4 deletions(-)
 create mode 100644 po/doc/local.mk

diff --git a/.gitignore b/.gitignore
index 4a110fb1f..f4119bc28 100644
--- a/.gitignore
+++ b/.gitignore
@@ -47,6 +47,7 @@
 /doc/os-config-desktop.texi
 /doc/stamp-vti
 /doc/version.texi
+/doc/version.*.texi
 /etc/guix-daemon.cil
 /etc/guix-daemon.conf
 /etc/guix-daemon.service
diff --git a/Makefile.am b/Makefile.am
index e2c940ca8..856075e7a 100644
--- a/Makefile.am
+++ b/Makefile.am
@@ -41,6 +41,8 @@ scripts/guix: scripts/guix.in Makefile
 	$(AM_V_GEN)$(do_subst) < "$(srcdir)/$@.in" > "$@-t"
 	$(AM_V_at)chmod a+x,a-w "$@-t" && mv -f "$@-t" "$@"
 
+doc/guix.fr.info: doc/guix.fr.texi
+
 nodist_noinst_SCRIPTS =				\
   pre-inst-env					\
   test-env
@@ -535,6 +537,7 @@ SUBDIRS = po/guix po/packages
 BUILT_SOURCES =
 
 include doc/local.mk
+include po/doc/local.mk
 
 if BUILD_DAEMON
 
diff --git a/doc/local.mk b/doc/local.mk
index 397ade050..f8aa31d5a 100644
--- a/doc/local.mk
+++ b/doc/local.mk
@@ -20,7 +20,8 @@
 # You should have received a copy of the GNU General Public License
 # along with GNU Guix.  If not, see <http://www.gnu.org/licenses/>.
 
-info_TEXINFOS = %D%/guix.texi
+info_TEXINFOS = %D%/guix.texi \
+  %D%/guix.fr.texi
 
 %C%_guix_TEXINFOS = \
   %D%/contributing.texi \
@@ -51,10 +52,22 @@ OS_CONFIG_EXAMPLES_TEXI =			\
   %D%/os-config-desktop.texi			\
   %D%/os-config-lightweight-desktop.texi
 
+TRANSLATED_INFO =			\
+  %D%/guix.fr.texi
+
 # Bundle this file so that makeinfo finds it in out-of-source-tree builds.
-BUILT_SOURCES        += $(OS_CONFIG_EXAMPLES_TEXI)
-EXTRA_DIST           += $(OS_CONFIG_EXAMPLES_TEXI)
-MAINTAINERCLEANFILES  = $(OS_CONFIG_EXAMPLES_TEXI)
+BUILT_SOURCES        += $(OS_CONFIG_EXAMPLES_TEXI) $(TRANSLATED_INFO)
+EXTRA_DIST           += $(OS_CONFIG_EXAMPLES_TEXI) $(TRANSLATED_INFO)
+MAINTAINERCLEANFILES  = $(OS_CONFIG_EXAMPLES_TEXI) $(TRANSLATED_INFO)
+
+PO4A_PARAMS:=-M UTF-8 -L UTF-8 #master and localized encoding
+PO4A_PARAMS+=-k 0 # produce an output even if the translation is not complete
+PO4A_PARAMS+=-f texinfo # texinfo format
+
+$(srcdir)/%D%/guix.%.texi: %D%/guix.texi po/doc/%.po
+	po4a-translate $(PO4A_PARAMS) -m $< -p $(word 2,$^) -l $@.tmp
+	sed -i 's|guix\.info|guix.fr.info|' $@.tmp
+	mv $@.tmp $@
 
 %D%/os-config-%.texi: gnu/system/examples/%.tmpl
 	$(AM_V_GEN)$(MKDIR_P) "`dirname $@`";	\
diff --git a/po/doc/local.mk b/po/doc/local.mk
new file mode 100644
index 000000000..84d43123d
--- /dev/null
+++ b/po/doc/local.mk
@@ -0,0 +1,23 @@
+# GNU Guix --- Functional package management for GNU
+# Copyright © 2018 Julien Lepiller <julien@lepiller.eu>
+#
+# This file is part of GNU Guix.
+#
+# GNU Guix is free software; you can redistribute it and/or modify it
+# under the terms of the GNU General Public License as published by
+# the Free Software Foundation; either version 3 of the License, or (at
+# your option) any later version.
+#
+# GNU Guix is distributed in the hope that it will be useful, but
+# WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+# GNU General Public License for more details.
+#
+# You should have received a copy of the GNU General Public License
+# along with GNU Guix.  If not, see <http://www.gnu.org/licenses/>.
+
+EXTRA_DIST += \
+  %D%/fr.po
+
+$(srcdir)/po/doc/%.po: doc/guix.texi
+	po4a-updatepo -M UTF-8 -f texinfo -m $< -p $@
-- 
2.16.1

Re: [WIP]: localize guix.texi

[Ludovic Courtès]

Hi Julien,

Thanks a lot for taking this initiative.  To me localization is super
important if we are to make free software a viable option for everyone.

Julien Lepiller <julien@lepiller.eu> skribis:

>> here is my first attempt at localizing guix.texi. This patch adds
>> guix.fr.texi, a localized version of the manual. It uses po4a to
>> generate the .po file and use that same file to generate the localized
>> manual.

From the patch I can’t really see how translation works.  Do translators
get a list of msgids to translate?

>> I had to include the guix.fr.texi in the commit because it is
>> necessary that it exists in order to add it to info_TEXINFOS. This
>> means that this version of guix now requires po4a and will always
>> build the localized manuals in every available language. I don't
>> really like that though.

What about doing what we do for man pages?  We include generated man
pages in the distributed tarball (that’s what the ‘dist_’ prefix in
‘dist_man1_MANS’ means, in doc/local.mk).  Thus help2man is needed only
if you’re building from a checkout.  Furthermore, we use AM_MISSING_PROG
so that users get a helpful message if they end up in a situation where
they would need help2man.

> From 7443ce7407a7194a9d9487f95f940b4b9adf5d82 Mon Sep 17 00:00:00 2001
> From: Julien Lepiller <julien@lepiller.eu>
> Date: Mon, 19 Feb 2018 23:24:30 +0100
> Subject: [PATCH] doc: Allow documentation to be translated.
>
> po/doc/local.mk: New file.
> Makefile.am: Include it.
> doc/local.mk (info_TEXINFOS, BUILT_SOURCES, EXTRA_DIST, MAINTAINERCLEANFILES):
> Add guix.fr.texi
> (rules): New rule to build localized texi files
> .gitignore: Ignore doc/version.*.texi

You’re missing bullets for each item here.  :-)

> +PO4A_PARAMS:=-M UTF-8 -L UTF-8 #master and localized encoding
> +PO4A_PARAMS+=-k 0 # produce an output even if the translation is not complete
> +PO4A_PARAMS+=-f texinfo # texinfo format

Nitpick: leave spaces around assignment operators.

> +$(srcdir)/%D%/guix.%.texi: %D%/guix.texi po/doc/%.po
> +	po4a-translate $(PO4A_PARAMS) -m $< -p $(word 2,$^) -l $@.tmp
> +	sed -i 's|guix\.info|guix.fr.info|' $@.tmp
> +	mv $@.tmp $@

[...]

> +$(srcdir)/po/doc/%.po: doc/guix.texi
> +	po4a-updatepo -M UTF-8 -f texinfo -m $< -p $@

If you use AM_MISSING_PROG, then you can use $(PO4A_TRANSLATE) and
$(PO4A_UPDATEPO) instead of directly using the program names here.

Last thing: please enclose file names in double quotes: "$@", "$<", etc.

With these changes, I’m all for applying the patch to master.

Thank you!

Ludo’.

Re: [WIP]: localize guix.texi

[Gábor Boskovits]

[-- Attachment #1: Type: text/plain, Size: 2998 bytes --]

2018-03-02 14:31 GMT+01:00 Ludovic Courtès <ludo@gnu.org>:

> Hi Julien,
>
> Thanks a lot for taking this initiative.  To me localization is super
> important if we are to make free software a viable option for everyone.
>
> Julien Lepiller <julien@lepiller.eu> skribis:
>
> >> here is my first attempt at localizing guix.texi. This patch adds
> >> guix.fr.texi, a localized version of the manual. It uses po4a to
> >> generate the .po file and use that same file to generate the localized
> >> manual.
>
> From the patch I can’t really see how translation works.  Do translators
> get a list of msgids to translate?
>
> >> I had to include the guix.fr.texi in the commit because it is
> >> necessary that it exists in order to add it to info_TEXINFOS. This
> >> means that this version of guix now requires po4a and will always
> >> build the localized manuals in every available language. I don't
> >> really like that though.
>
> What about doing what we do for man pages?  We include generated man
> pages in the distributed tarball (that’s what the ‘dist_’ prefix in
> ‘dist_man1_MANS’ means, in doc/local.mk).  Thus help2man is needed only
> if you’re building from a checkout.  Furthermore, we use AM_MISSING_PROG
> so that users get a helpful message if they end up in a situation where
> they would need help2man.
>
> > From 7443ce7407a7194a9d9487f95f940b4b9adf5d82 Mon Sep 17 00:00:00 2001
> > From: Julien Lepiller <julien@lepiller.eu>
> > Date: Mon, 19 Feb 2018 23:24:30 +0100
> > Subject: [PATCH] doc: Allow documentation to be translated.
> >
> > po/doc/local.mk: New file.
> > Makefile.am: Include it.
> > doc/local.mk (info_TEXINFOS, BUILT_SOURCES, EXTRA_DIST,
> MAINTAINERCLEANFILES):
> > Add guix.fr.texi
> > (rules): New rule to build localized texi files
> > .gitignore: Ignore doc/version.*.texi
>
> You’re missing bullets for each item here.  :-)
>
> > +PO4A_PARAMS:=-M UTF-8 -L UTF-8 #master and localized encoding
> > +PO4A_PARAMS+=-k 0 # produce an output even if the translation is not
> complete
> > +PO4A_PARAMS+=-f texinfo # texinfo format
>
> Nitpick: leave spaces around assignment operators.
>
> > +$(srcdir)/%D%/guix.%.texi: %D%/guix.texi po/doc/%.po
> > +     po4a-translate $(PO4A_PARAMS) -m $< -p $(word 2,$^) -l $@.tmp
> > +     sed -i 's|guix\.info|guix.fr.info|' $@.tmp
> > +     mv $@.tmp $@
>
> [...]
>
> > +$(srcdir)/po/doc/%.po: doc/guix.texi
> > +     po4a-updatepo -M UTF-8 -f texinfo -m $< -p $@
>
> If you use AM_MISSING_PROG, then you can use $(PO4A_TRANSLATE) and
> $(PO4A_UPDATEPO) instead of directly using the program names here.
>
> Last thing: please enclose file names in double quotes: "$@", "$<", etc.
>
> With these changes, I’m all for applying the patch to master.
>
>
Once this is in master I'm also willing to do this for my language. I'm
waiting for
the final style to settle. Thanks for the initiative!


> Thank you!
>
> Ludo’.
>
>

[-- Attachment #2: Type: text/html, Size: 4160 bytes --]

[WIP] localize guix.texi

[Julien Lepiller]

Hi, this new version of the patch takes your feedback into account. I tried
to put guix.fr.texi in dist_info_TEXINFOS, but automake didn't generate the
rules for building guix.fr.info in that case.

I don't like the fact that both the po and texi files are commited and will
be changed together whenever someone makes a change in the manual.

The French translation is just the beginning: I translated only the Introduction
and the Installation pages. Also, I used the po file to add the
@documentlanguage macro to change the texinfo strings to French (like "see",
"next page", "up", etc).

There's an issue with changes that add references: when that happens, the
default translation would be the English version, so the reference would be
to the English name (for instance, @pxref{Invoking guix package}), resulting
in a build failure when the name has been changed (for instance
"Invoquer guix package" in French). I would like to be able to localize the
section name because it appears in link names. Any ideas?

[PATCH 1/3] gnu: doc: Alloc documentation to be translated.

[Julien Lepiller]

* po/doc/local.mk: New file.
* Makefile.am: Include it. Add silent rules for po4a.
* configure.ac: Look for po4a-translate and po4a-updatepo.
* doc/local.mk: Add rules to generate gettext files.
(TRANSLATED_INFO): New variable.
(BUILT_SOURCES, EXTRA_DIST, MAINTAINERCLEANFILES): Add it.
* .gitignore: Add generated files.
---
 .gitignore      | 17 +++++++++++++++++
 Makefile.am     |  8 +++++++-
 configure.ac    |  4 ++++
 doc/local.mk    | 22 +++++++++++++++++++---
 po/doc/local.mk | 27 +++++++++++++++++++++++++++
 5 files changed, 74 insertions(+), 4 deletions(-)
 create mode 100644 po/doc/local.mk

diff --git a/.gitignore b/.gitignore
index 4a110fb1f..0145a7d86 100644
--- a/.gitignore
+++ b/.gitignore
@@ -28,6 +28,21 @@
 /configure
 /doc/*.1
 /doc/.dirstamp
+/doc/guix.*.aux
+/doc/guix.*.cp
+/doc/guix.*.cps
+/doc/guix.*.fn
+/doc/guix.*.fns
+/doc/guix.*.html
+/doc/guix.*.info
+/doc/guix.*.info-[0-9]
+/doc/guix.*.ky
+/doc/guix.*.pg
+/doc/guix.*.toc
+/doc/guix.*.t2p
+/doc/guix.*.tp
+/doc/guix.*.vr
+/doc/guix.*.vrs
 /doc/guix.aux
 /doc/guix.cp
 /doc/guix.cps
@@ -47,6 +62,7 @@
 /doc/os-config-desktop.texi
 /doc/stamp-vti
 /doc/version.texi
+/doc/version.*.texi
 /etc/guix-daemon.cil
 /etc/guix-daemon.conf
 /etc/guix-daemon.service
@@ -79,6 +95,7 @@
 /nix/scripts/list-runtime-roots
 /nix/scripts/offload
 /nix/scripts/substitute
+/po/doc/*.mo
 /po/guix/*.gmo
 /po/guix/*.insert-header
 /po/guix/*.mo
diff --git a/Makefile.am b/Makefile.am
index 6556799e6..757ca9b2f 100644
--- a/Makefile.am
+++ b/Makefile.am
@@ -10,6 +10,7 @@
 # Copyright © 2017 Jan Nieuwenhuizen <janneke@gnu.org>
 # Copyright © 2017 Arun Isaac <arunisaac@systemreboot.net>
 # Copyright © 2018 ng0 <ng0@n0.is>
+# Copyright © 2018 Julien Lepiller <julien@lepiller.eu>
 #
 # This file is part of GNU Guix.
 #
@@ -51,6 +52,7 @@ MODULES_NOT_COMPILED =				\
   guix/man-db.scm
 
 include gnu/local.mk
+include po/doc/local.mk
 
 MODULES =					\
   guix/base16.scm				\
@@ -451,7 +453,7 @@ dist_fishcompletion_DATA = etc/completion/fish/guix.fish
 # SELinux policy
 dist_selinux_policy_DATA = etc/guix-daemon.cil
 
-EXTRA_DIST =						\
+EXTRA_DIST +=						\
   HACKING						\
   ROADMAP						\
   TODO							\
@@ -778,3 +780,7 @@ AM_V_DOT_0 = @echo "  DOT     " $@;
 AM_V_HELP2MAN = $(AM_V_HELP2MAN_$(V))
 AM_V_HELP2MAN_ = $(AM_V_HELP2MAN_$(AM_DEFAULT_VERBOSITY))
 AM_V_HELP2MAN_0 = @echo "  HELP2MAN" $@;
+
+AM_V_PO4A = $(AM_V_PO4A_$(V))
+AM_V_PO4A_ = $(AM_V_PO4A_$(AM_DEFAULT_VERBOSITY))
+AM_V_PO4A_0 = @echo "  PO4A" $@;
diff --git a/configure.ac b/configure.ac
index 5872a8482..557da6318 100644
--- a/configure.ac
+++ b/configure.ac
@@ -263,6 +263,10 @@ AM_MISSING_PROG([DOT], [dot])
 dnl Manual pages.
 AM_MISSING_PROG([HELP2MAN], [help2man])
 
+dnl Documentation translation.
+AM_MISSING_PROG([PO4A_TRANSLATE], [po4a-translate])
+AM_MISSING_PROG([PO4A_UPDATEPO], [po4a-updatepo])
+
 dnl Emacs (optional), for 'etc/indent-package.el'.
 AC_PATH_PROG([EMACS], [emacs], [/usr/bin/emacs])
 AC_SUBST([EMACS])
diff --git a/doc/local.mk b/doc/local.mk
index 397ade050..f8cf969aa 100644
--- a/doc/local.mk
+++ b/doc/local.mk
@@ -4,6 +4,7 @@
 # Copyright © 2013 Andreas Enge <andreas@enge.fr>
 # Copyright © 2016 Taylan Ulrich Bayırlı/Kammer <taylanbayirli@gmail.com>
 # Copyright © 2016, 2018 Mathieu Lirzin <mthl@gnu.org>
+# Copyright © 2018 Julien Lepiller <julien@lepiller.eu>
 #
 # This file is part of GNU Guix.
 #
@@ -51,10 +52,25 @@ OS_CONFIG_EXAMPLES_TEXI =			\
   %D%/os-config-desktop.texi			\
   %D%/os-config-lightweight-desktop.texi
 
+TRANSLATED_INFO =
+
 # Bundle this file so that makeinfo finds it in out-of-source-tree builds.
-BUILT_SOURCES        += $(OS_CONFIG_EXAMPLES_TEXI)
-EXTRA_DIST           += $(OS_CONFIG_EXAMPLES_TEXI)
-MAINTAINERCLEANFILES  = $(OS_CONFIG_EXAMPLES_TEXI)
+BUILT_SOURCES        += $(OS_CONFIG_EXAMPLES_TEXI) $(TRANSLATED_INFO)
+EXTRA_DIST           += $(OS_CONFIG_EXAMPLES_TEXI) $(TRANSLATED_INFO)
+MAINTAINERCLEANFILES  = $(OS_CONFIG_EXAMPLES_TEXI) $(TRANSLATED_INFO)
+
+PO4A_PARAMS := -M UTF-8 -L UTF-8 #master and localized encoding
+PO4A_PARAMS += -k 0 # produce an output even if the translation is not complete
+PO4A_PARAMS += -f texinfo # texinfo format
+
+$(srcdir)/%D%/guix.%.texi: %D%/guix.texi po/doc/guix.%.po
+	-$(AM_V_PO4A)$(PO4A_TRANSLATE) $(PO4A_PARAMS) -m "$<" -p "$(word 2,$^)" -l "$@.tmp"
+	sed -i "s|guix\.info|$$(basename $@ | sed 's|texi$$|info|')|" "$@.tmp"
+	mv "$@.tmp" "$@"
+
+$(srcdir)/%D%/contributing.%.texi: %D%/contributing.texi po/doc/contributing.%.po
+	-$(AM_V_PO4A)$(PO4A_TRANSLATE) $(PO4A_PARAMS) -m "$<" -p "$(word 2,$^)" -l "$@"
+	-touch "$@"
 
 %D%/os-config-%.texi: gnu/system/examples/%.tmpl
 	$(AM_V_GEN)$(MKDIR_P) "`dirname $@`";	\
diff --git a/po/doc/local.mk b/po/doc/local.mk
new file mode 100644
index 000000000..0e4ad352c
--- /dev/null
+++ b/po/doc/local.mk
@@ -0,0 +1,27 @@
+# GNU Guix --- Functional package management for GNU
+# Copyright © 2018 Julien Lepiller <julien@lepiller.eu>
+#
+# This file is part of GNU Guix.
+#
+# GNU Guix is free software; you can redistribute it and/or modify it
+# under the terms of the GNU General Public License as published by
+# the Free Software Foundation; either version 3 of the License, or (at
+# your option) any later version.
+#
+# GNU Guix is distributed in the hope that it will be useful, but
+# WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+# GNU General Public License for more details.
+#
+# You should have received a copy of the GNU General Public License
+# along with GNU Guix.  If not, see <http://www.gnu.org/licenses/>.
+
+EXTRA_DIST =
+
+$(srcdir)/po/doc/contributing.%.po: doc/contributing.texi
+	-$(AM_V_PO4A)$(PO4A_UPDATEPO) -M UTF-8 -f texinfo -m "$<" -p "$@"
+	-touch "$@"
+
+$(srcdir)/po/doc/guix.%.po: doc/guix.texi
+	-$(AM_V_PO4A)$(PO4A_UPDATEPO) -M UTF-8 -f texinfo -m "$<" -p "$@"
+	-touch "$@"
-- 
2.16.1

Re: [PATCH 1/3] gnu: doc: Alloc documentation to be translated.

[Ludovic Courtès]

Julien Lepiller <julien@lepiller.eu> skribis:

> * po/doc/local.mk: New file.
> * Makefile.am: Include it. Add silent rules for po4a.
> * configure.ac: Look for po4a-translate and po4a-updatepo.
> * doc/local.mk: Add rules to generate gettext files.
> (TRANSLATED_INFO): New variable.
> (BUILT_SOURCES, EXTRA_DIST, MAINTAINERCLEANFILES): Add it.
> * .gitignore: Add generated files.

LGTM!

For good measure, please check whether “make distcheck” doesn’t show any
regression (I haven’t checked in recent master though, it could be that
there are currently unrelated issues.)

Thanks,
Ludo’.

Re: [PATCH 1/3] gnu: doc: Alloc documentation to be translated.

[Julien Lepiller]

[-- Attachment #1: Type: text/plain, Size: 1138 bytes --]

Le Mon, 05 Mar 2018 10:10:19 +0100,
ludo@gnu.org (Ludovic Courtès) a écrit :

> Julien Lepiller <julien@lepiller.eu> skribis:
> 
> > * po/doc/local.mk: New file.
> > * Makefile.am: Include it. Add silent rules for po4a.
> > * configure.ac: Look for po4a-translate and po4a-updatepo.
> > * doc/local.mk: Add rules to generate gettext files.
> > (TRANSLATED_INFO): New variable.
> > (BUILT_SOURCES, EXTRA_DIST, MAINTAINERCLEANFILES): Add it.
> > * .gitignore: Add generated files.  
> 
> LGTM!
> 
> For good measure, please check whether “make distcheck” doesn’t show
> any regression (I haven’t checked in recent master though, it could
> be that there are currently unrelated issues.)
> 
> Thanks,
> Ludo’.

Here is a newer version of the patches. I "fixed" the issue with
translated references, but a change in the English manual will still
create a change in the translated manuals and po files.

I tried to run make distcheck, but even on master, I get this error
message:

make[2]: ***  Aucune règle pour fabriquer la cible « bin/guix.in »,
nécessaire pour « distdir-am ». Arrêt.

[-- Warning: decoded text below may be mangled, UTF-8 assumed --]
[-- Attachment #2: 0001-gnu-doc-Alloc-documentation-to-be-translated.patch --]
[-- Type: text/x-patch, Size: 7814 bytes --]

From bbad37ae7ca918c894f4aa4d46f6694991a97f29 Mon Sep 17 00:00:00 2001
From: Julien Lepiller <julien@lepiller.eu>
Date: Fri, 2 Mar 2018 23:05:28 +0100
Subject: [PATCH 1/3] gnu: doc: Alloc documentation to be translated.

* po/doc/local.mk: New file.
* Makefile.am: Include it. Add silent rules for po4a.
* configure.ac: Look for po4a-translate and po4a-updatepo.
* doc/local.mk: Add rules to generate gettext files.
(TRANSLATED_INFO): New variable.
(BUILT_SOURCES, EXTRA_DIST, MAINTAINERCLEANFILES): Add it.
* .gitignore: Add generated files.
---
 .gitignore      | 17 +++++++++++++++++
 Makefile.am     |  8 +++++++-
 configure.ac    |  4 ++++
 doc/local.mk    | 48 +++++++++++++++++++++++++++++++++++++++++++++---
 po/doc/local.mk | 27 +++++++++++++++++++++++++++
 5 files changed, 100 insertions(+), 4 deletions(-)
 create mode 100644 po/doc/local.mk

diff --git a/.gitignore b/.gitignore
index 4a110fb1f..38a55a3b5 100644
--- a/.gitignore
+++ b/.gitignore
@@ -28,6 +28,21 @@
 /configure
 /doc/*.1
 /doc/.dirstamp
+/doc/guix.*.aux
+/doc/guix.*.cp
+/doc/guix.*.cps
+/doc/guix.*.fn
+/doc/guix.*.fns
+/doc/guix.*.html
+/doc/guix.*.info
+/doc/guix.*.info-[0-9]
+/doc/guix.*.ky
+/doc/guix.*.pg
+/doc/guix.*.toc
+/doc/guix.*.t2p
+/doc/guix.*.tp
+/doc/guix.*.vr
+/doc/guix.*.vrs
 /doc/guix.aux
 /doc/guix.cp
 /doc/guix.cps
@@ -47,6 +62,7 @@
 /doc/os-config-desktop.texi
 /doc/stamp-vti
 /doc/version.texi
+/doc/version-*.texi
 /etc/guix-daemon.cil
 /etc/guix-daemon.conf
 /etc/guix-daemon.service
@@ -79,6 +95,7 @@
 /nix/scripts/list-runtime-roots
 /nix/scripts/offload
 /nix/scripts/substitute
+/po/doc/*.mo
 /po/guix/*.gmo
 /po/guix/*.insert-header
 /po/guix/*.mo
diff --git a/Makefile.am b/Makefile.am
index feb99490d..36f5856b4 100644
--- a/Makefile.am
+++ b/Makefile.am
@@ -10,6 +10,7 @@
 # Copyright © 2017 Jan Nieuwenhuizen <janneke@gnu.org>
 # Copyright © 2017 Arun Isaac <arunisaac@systemreboot.net>
 # Copyright © 2018 Nils Gillmann <ng0@n0.is>
+# Copyright © 2018 Julien Lepiller <julien@lepiller.eu>
 #
 # This file is part of GNU Guix.
 #
@@ -51,6 +52,7 @@ MODULES_NOT_COMPILED =				\
   guix/man-db.scm
 
 include gnu/local.mk
+include po/doc/local.mk
 
 MODULES =					\
   guix/base16.scm				\
@@ -452,7 +454,7 @@ dist_fishcompletion_DATA = etc/completion/fish/guix.fish
 # SELinux policy
 dist_selinux_policy_DATA = etc/guix-daemon.cil
 
-EXTRA_DIST =						\
+EXTRA_DIST +=						\
   HACKING						\
   ROADMAP						\
   TODO							\
@@ -779,3 +781,7 @@ AM_V_DOT_0 = @echo "  DOT     " $@;
 AM_V_HELP2MAN = $(AM_V_HELP2MAN_$(V))
 AM_V_HELP2MAN_ = $(AM_V_HELP2MAN_$(AM_DEFAULT_VERBOSITY))
 AM_V_HELP2MAN_0 = @echo "  HELP2MAN" $@;
+
+AM_V_PO4A = $(AM_V_PO4A_$(V))
+AM_V_PO4A_ = $(AM_V_PO4A_$(AM_DEFAULT_VERBOSITY))
+AM_V_PO4A_0 = @echo "  PO4A" $@;
diff --git a/configure.ac b/configure.ac
index 5872a8482..557da6318 100644
--- a/configure.ac
+++ b/configure.ac
@@ -263,6 +263,10 @@ AM_MISSING_PROG([DOT], [dot])
 dnl Manual pages.
 AM_MISSING_PROG([HELP2MAN], [help2man])
 
+dnl Documentation translation.
+AM_MISSING_PROG([PO4A_TRANSLATE], [po4a-translate])
+AM_MISSING_PROG([PO4A_UPDATEPO], [po4a-updatepo])
+
 dnl Emacs (optional), for 'etc/indent-package.el'.
 AC_PATH_PROG([EMACS], [emacs], [/usr/bin/emacs])
 AC_SUBST([EMACS])
diff --git a/doc/local.mk b/doc/local.mk
index 397ade050..922d7581a 100644
--- a/doc/local.mk
+++ b/doc/local.mk
@@ -4,6 +4,7 @@
 # Copyright © 2013 Andreas Enge <andreas@enge.fr>
 # Copyright © 2016 Taylan Ulrich Bayırlı/Kammer <taylanbayirli@gmail.com>
 # Copyright © 2016, 2018 Mathieu Lirzin <mthl@gnu.org>
+# Copyright © 2018 Julien Lepiller <julien@lepiller.eu>
 #
 # This file is part of GNU Guix.
 #
@@ -51,10 +52,51 @@ OS_CONFIG_EXAMPLES_TEXI =			\
   %D%/os-config-desktop.texi			\
   %D%/os-config-lightweight-desktop.texi
 
+TRANSLATED_INFO =
+
 # Bundle this file so that makeinfo finds it in out-of-source-tree builds.
-BUILT_SOURCES        += $(OS_CONFIG_EXAMPLES_TEXI)
-EXTRA_DIST           += $(OS_CONFIG_EXAMPLES_TEXI)
-MAINTAINERCLEANFILES  = $(OS_CONFIG_EXAMPLES_TEXI)
+BUILT_SOURCES        += $(OS_CONFIG_EXAMPLES_TEXI) $(TRANSLATED_INFO)
+EXTRA_DIST           += $(OS_CONFIG_EXAMPLES_TEXI) $(TRANSLATED_INFO)
+MAINTAINERCLEANFILES  = $(OS_CONFIG_EXAMPLES_TEXI) $(TRANSLATED_INFO)
+
+PO4A_PARAMS := -M UTF-8 -L UTF-8 #master and localized encoding
+PO4A_PARAMS += -k 0 # produce an output even if the translation is not complete
+PO4A_PARAMS += -f texinfo # texinfo format
+
+# When a change to guix.texi occurs, it is not translated immediately.
+# Because @pxref and @xref commands are reference to a section by name, they
+# should be translated. If a modification adds a reference to a section, this
+# reference is not translated, which means it references a section that does not
+# exist.
+# This command loops through the translated files looking for references. For
+# each of these references, it tries to find the translation and replaces the
+# reference name, even in untranslated strings.
+# The last sed is a multiline sed because some references span multiple lines.
+define xref_command
+cat "$@.tmp" | egrep '@p?x?ref' -A1 | sed 'N;s|--\n||g;P;D' | sed 's|^| |g' | \
+        tr -d '\012' | sed 's|\(@p\?x\?ref\)|\n\1|g' | egrep '@p?x?ref' | \
+        sed 's|^.*@p\?x\?ref{\([^,}]*\).*$$|\1|g' | sort | uniq | while read e; do \
+  line=$$(grep -n "msgid \"$$e\"" "$(word 2,$^)" | cut -f1 --delimiter=":") ;\
+  ((line++)) ;\
+  if [ "$$line" != "1" ]; then \
+    translation=$$(head -n $$line "$(word 2,$^)" | tail -1 | grep msgstr | sed 's|msgstr "\(.*\)"|\1|') ;\
+    if [ "$$translation" != "" ]; then \
+	  sed "N;s@\(p\?x\?ref\){$$(echo $$e | sed 's| |[\\n ]|g')\(,\|}\)@\1{$$translation\2@g;P;D" -i "$@.tmp" ;\
+    fi ;\
+  fi ;\
+done
+endef
+
+$(srcdir)/%D%/guix.%.texi: %D%/guix.texi po/doc/guix.%.po $(srcdir)/%D%/contributing.%.texi
+	-$(AM_V_PO4A)$(PO4A_TRANSLATE) $(PO4A_PARAMS) -m "$<" -p "$(word 2,$^)" -l "$@.tmp"
+	-sed -i "s|guix\.info|$$(basename "$@" | sed 's|texi$$|info|')|" "$@.tmp"
+	-$(xref_command)
+	-mv "$@.tmp" "$@"
+
+$(srcdir)/%D%/contributing.%.texi: %D%/contributing.texi po/doc/guix.%.po po/doc/contributing.%.po
+	-$(AM_V_PO4A)$(PO4A_TRANSLATE) $(PO4A_PARAMS) -m "$<" -p "$(word 3,$^)" -l "$@.tmp"
+	-$(xref_command)
+	-mv "$@.tmp" "$@"
 
 %D%/os-config-%.texi: gnu/system/examples/%.tmpl
 	$(AM_V_GEN)$(MKDIR_P) "`dirname $@`";	\
diff --git a/po/doc/local.mk b/po/doc/local.mk
new file mode 100644
index 000000000..0e4ad352c
--- /dev/null
+++ b/po/doc/local.mk
@@ -0,0 +1,27 @@
+# GNU Guix --- Functional package management for GNU
+# Copyright © 2018 Julien Lepiller <julien@lepiller.eu>
+#
+# This file is part of GNU Guix.
+#
+# GNU Guix is free software; you can redistribute it and/or modify it
+# under the terms of the GNU General Public License as published by
+# the Free Software Foundation; either version 3 of the License, or (at
+# your option) any later version.
+#
+# GNU Guix is distributed in the hope that it will be useful, but
+# WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+# GNU General Public License for more details.
+#
+# You should have received a copy of the GNU General Public License
+# along with GNU Guix.  If not, see <http://www.gnu.org/licenses/>.
+
+EXTRA_DIST =
+
+$(srcdir)/po/doc/contributing.%.po: doc/contributing.texi
+	-$(AM_V_PO4A)$(PO4A_UPDATEPO) -M UTF-8 -f texinfo -m "$<" -p "$@"
+	-touch "$@"
+
+$(srcdir)/po/doc/guix.%.po: doc/guix.texi
+	-$(AM_V_PO4A)$(PO4A_UPDATEPO) -M UTF-8 -f texinfo -m "$<" -p "$@"
+	-touch "$@"
-- 
2.16.3


[-- Warning: decoded text below may be mangled, UTF-8 assumed --]
[-- Attachment #3: 0002-gnu-guix-Add-po4a-input.patch --]
[-- Type: text/x-patch, Size: 1282 bytes --]

From 8b5871cfc00f15dfe22131eaa4ba5b5fc6458c24 Mon Sep 17 00:00:00 2001
From: Julien Lepiller <julien@lepiller.eu>
Date: Fri, 2 Mar 2018 23:11:46 +0100
Subject: [PATCH 2/3] gnu: guix: Add po4a input.

* gnu/packages/package-management.scm (guix)[inputs]: Add po4a.
---
 gnu/packages/package-management.scm | 4 +++-
 1 file changed, 3 insertions(+), 1 deletion(-)

diff --git a/gnu/packages/package-management.scm b/gnu/packages/package-management.scm
index a90ba7a21..f86afb1cb 100644
--- a/gnu/packages/package-management.scm
+++ b/gnu/packages/package-management.scm
@@ -5,6 +5,7 @@
 ;;; Copyright © 2017 Oleg Pykhalov <go.wigust@gmail.com>
 ;;; Copyright © 2017 Roel Janssen <roel@gnu.org>
 ;;; Copyright © 2017, 2018 Tobias Geerinckx-Rice <me@tobias.gr>
+;;; Copyright © 2018 Julien Lepiller <julien@lepiller.eu>
 ;;;
 ;;; This file is part of GNU Guix.
 ;;;
@@ -244,7 +245,8 @@
                        ("gettext" ,gettext-minimal)
                        ("texinfo" ,texinfo)
                        ("graphviz" ,graphviz)
-                       ("help2man" ,help2man)))
+                       ("help2man" ,help2man)
+                       ("po4a" ,po4a)))
       (inputs
        `(("bzip2" ,bzip2)
          ("gzip" ,gzip)
-- 
2.16.3

Re: [PATCH 1/3] gnu: doc: Alloc documentation to be translated.

[Ludovic Courtès]

Hi Julien,

Julien Lepiller <julien@lepiller.eu> skribis:

> Le Mon, 05 Mar 2018 10:10:19 +0100,
> ludo@gnu.org (Ludovic Courtès) a écrit :

[...]

>> For good measure, please check whether “make distcheck” doesn’t show
>> any regression (I haven’t checked in recent master though, it could
>> be that there are currently unrelated issues.)
>> 
>> Thanks,
>> Ludo’.
>
> Here is a newer version of the patches. I "fixed" the issue with
> translated references, but a change in the English manual will still
> create a change in the translated manuals and po files.
>
> I tried to run make distcheck, but even on master, I get this error
> message:
>
> make[2]: ***  Aucune règle pour fabriquer la cible « bin/guix.in »,
> nécessaire pour « distdir-am ». Arrêt.

Fixed in c92e5612996e98cde005a572b83fc66aae32bcd7.

Could you try again and commit if it works?

Thanks,
Ludo’.

[PATCH 2/3] gnu: guix: Add po4a input.

[Julien Lepiller]

* gnu/packages/package-management.scm (guix)[inputs]: Add po4a.
---
 gnu/packages/package-management.scm | 4 +++-
 1 file changed, 3 insertions(+), 1 deletion(-)

diff --git a/gnu/packages/package-management.scm b/gnu/packages/package-management.scm
index 6ec70b12f..5aeea5cbd 100644
--- a/gnu/packages/package-management.scm
+++ b/gnu/packages/package-management.scm
@@ -5,6 +5,7 @@
 ;;; Copyright © 2017 Oleg Pykhalov <go.wigust@gmail.com>
 ;;; Copyright © 2017 Roel Janssen <roel@gnu.org>
 ;;; Copyright © 2017, 2018 Tobias Geerinckx-Rice <me@tobias.gr>
+;;; Copyright © 2018 Julien Lepiller <julien@lepiller.eu>
 ;;;
 ;;; This file is part of GNU Guix.
 ;;;
@@ -244,7 +245,8 @@
                        ("gettext" ,gettext-minimal)
                        ("texinfo" ,texinfo)
                        ("graphviz" ,graphviz)
-                       ("help2man" ,help2man)))
+                       ("help2man" ,help2man)
+                       ("po4a" ,po4a)))
       (inputs
        `(("bzip2" ,bzip2)
          ("gzip" ,gzip)
-- 
2.16.1

Re: [PATCH 2/3] gnu: guix: Add po4a input.

[Ludovic Courtès]

Julien Lepiller <julien@lepiller.eu> skribis:

> * gnu/packages/package-management.scm (guix)[inputs]: Add po4a.

OK.

And OK for patch 3/3, which I guess is the French translation.

Ludo’.

Re: [WIP] localize guix.texi

[Ludovic Courtès]

Hi,

Julien Lepiller <julien@lepiller.eu> skribis:

> Hi, this new version of the patch takes your feedback into account. I tried
> to put guix.fr.texi in dist_info_TEXINFOS, but automake didn't generate the
> rules for building guix.fr.info in that case.
>
> I don't like the fact that both the po and texi files are commited and will
> be changed together whenever someone makes a change in the manual.

I think this can be addressed by adding:

  PO_DEPENDS_ON_POT = no

in ‘Makevars’.  This variable is documented like this:

--8<---------------cut here---------------start------------->8---
# This tells whether or not to regenerate a PO file when $(DOMAIN).pot
# has changed.  Possible values are "yes" and "no".  Set this to no if
# the POT file is checked in the repository and the version control
# program ignores timestamps.
PO_DEPENDS_ON_POT = yes
--8<---------------cut here---------------end--------------->8---

> The French translation is just the beginning: I translated only the Introduction
> and the Installation pages. Also, I used the po file to add the
> @documentlanguage macro to change the texinfo strings to French (like "see",
> "next page", "up", etc).

Sounds good.  I think ‘makeinfo --html’ would also need to run in fr_FR
locale no?  Or does @documentlanguage take care of everything, including
strings automatically added by makeinfo, such as those that appear at
the top of each HTML page?

> There's an issue with changes that add references: when that happens, the
> default translation would be the English version, so the reference would be
> to the English name (for instance, @pxref{Invoking guix package}), resulting
> in a build failure when the name has been changed (for instance
> "Invoquer guix package" in French). I would like to be able to localize the
> section name because it appears in link names. Any ideas?

No idea.  Can po4a help with that?

At worst, if .po files are committed and not systematically generated,
we can let translators handle this before they commit?

Thanks,
Ludo’.

Re: [WIP] localize guix.texi

[julien lepiller]

Le 2018-03-05 10:08, ludo@gnu.org a écrit :
> Hi,
> 
> Julien Lepiller <julien@lepiller.eu> skribis:
> 
>> Hi, this new version of the patch takes your feedback into account. I 
>> tried
>> to put guix.fr.texi in dist_info_TEXINFOS, but automake didn't 
>> generate the
>> rules for building guix.fr.info in that case.
>> 
>> I don't like the fact that both the po and texi files are commited and 
>> will
>> be changed together whenever someone makes a change in the manual.
> 
> I think this can be addressed by adding:
> 
>   PO_DEPENDS_ON_POT = no
> 
> in ‘Makevars’.  This variable is documented like this:
> 
> --8<---------------cut here---------------start------------->8---
> # This tells whether or not to regenerate a PO file when $(DOMAIN).pot
> # has changed.  Possible values are "yes" and "no".  Set this to no if
> # the POT file is checked in the repository and the version control
> # program ignores timestamps.
> PO_DEPENDS_ON_POT = yes
> --8<---------------cut here---------------end--------------->8---

Well, since there's no pot file, it doesn't really help.

> 
>> The French translation is just the beginning: I translated only the 
>> Introduction
>> and the Installation pages. Also, I used the po file to add the
>> @documentlanguage macro to change the texinfo strings to French (like 
>> "see",
>> "next page", "up", etc).
> 
> Sounds good.  I think ‘makeinfo --html’ would also need to run in fr_FR
> locale no?  Or does @documentlanguage take care of everything, 
> including
> strings automatically added by makeinfo, such as those that appear at
> the top of each HTML page?

@documentlanguage is enough

> 
>> There's an issue with changes that add references: when that happens, 
>> the
>> default translation would be the English version, so the reference 
>> would be
>> to the English name (for instance, @pxref{Invoking guix package}), 
>> resulting
>> in a build failure when the name has been changed (for instance
>> "Invoquer guix package" in French). I would like to be able to 
>> localize the
>> section name because it appears in link names. Any ideas?
> 
> No idea.  Can po4a help with that?

It doesn't seem so. But that may be an improvement of po4a.

> 
> At worst, if .po files are committed and not systematically generated,
> we can let translators handle this before they commit?

I don't understand? The issue is when translators are not involved. IIUC 
in
texinfo, the section name (reference) and title (displayed) are the 
same, so
section names have to be translated. When someone makes a change to the 
English
manual and adds a reference to an existing section, po4a cannot generate 
a
translation, so it will leave it as is. So we will get a reference to an 
invalid
section in the translated manuals and they will refuse to build.

There is enough information in the po file though, so I think po4a can 
be
improved (or we could add our own script for that).

Thank you!

> 
> Thanks,
> Ludo’.

Re: [WIP] localize guix.texi

[Ludovic Courtès]

Hi,

julien lepiller <julien@lepiller.eu> skribis:

> Le 2018-03-05 10:08, ludo@gnu.org a écrit :

[...]

>> I think this can be addressed by adding:
>>
>>   PO_DEPENDS_ON_POT = no
>>
>> in ‘Makevars’.  This variable is documented like this:
>>
>> --8<---------------cut here---------------start------------->8---
>> # This tells whether or not to regenerate a PO file when $(DOMAIN).pot
>> # has changed.  Possible values are "yes" and "no".  Set this to no if
>> # the POT file is checked in the repository and the version control
>> # program ignores timestamps.
>> PO_DEPENDS_ON_POT = yes
>> --8<---------------cut here---------------end--------------->8---
>
> Well, since there's no pot file, it doesn't really help.

Oh, I thought po4a would generate a pot file from the texi source.

>> At worst, if .po files are committed and not systematically generated,
>> we can let translators handle this before they commit?
>
> I don't understand? The issue is when translators are not
> involved. IIUC in
> texinfo, the section name (reference) and title (displayed) are the
> same, so
> section names have to be translated. When someone makes a change to
> the English
> manual and adds a reference to an existing section, po4a cannot
> generate a
> translation, so it will leave it as is. So we will get a reference to
> an invalid
> section in the translated manuals and they will refuse to build.

Right, but the “we” in the sentence above corresponds to translators,
right?  As long as only translators see the problem, that should be
fine.

> There is enough information in the po file though, so I think po4a can
> be
> improved (or we could add our own script for that).

Great.

Thanks!

Ludo’.