Re: [WIP] localize guix.texi

[Ludovic Courtès]

Hi,

julien lepiller  skribis:

> Le 2018-03-05 10:08, l...@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’.

Re: [WIP] localize guix.texi

[julien lepiller]

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

Hi,

Julien Lepiller  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  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’.

[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?

Re: [WIP]: localize guix.texi

[Gábor Boskovits]

2018-03-02 14:31 GMT+01:00 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  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 
> > 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’.
>
>

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  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 
> 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

[Julien Lepiller]

Le Mon, 19 Feb 2018 23:34:37 +0100,
Julien Lepiller  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.
From 7443ce7407a7194a9d9487f95f940b4b9adf5d82 Mon Sep 17 00:00:00 2001
From: Julien Lepiller 
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 .
 
-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 0..84d43123d
--- /dev/null
+++ b/po/doc/local.mk
@@ -0,0 +1,23 @@
+# GNU Guix --- Functional package management for GNU
+# Copyright © 2018 Julien Lepiller 
+#
+# 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 .
+
+EXTRA_DIST += \
+  %D%/fr.po
+
+$(srcdir)/po/doc/%.po: doc/guix.texi
+	po4a-updatepo -M UTF-8 -f texinfo -m $< -p $@
-- 
2.16.1

[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?