advice on po/pot/po4a layout etc.

[Ian Jackson]

Hi. I hope this is a suitable list for my question. If not, please
direct me elsewhere...


I am doing the i18n for a package (src:dgit) which I think it will be
useful to translate (at least, much of it). It's a Debian native
package containing mostly perl scripts.

I'm not sure of the best approach. My main questions:


1. There doesn't seem to be any standard set of Makefile machiner to
include, or anything. Do I really have to write my own make rules to
run xgettext etc. ? I looked at the debconf source package, which
seemed like it would be a good example, and it had its own rules. I
can write my own rules if that is best; they're not huge. It just
seemed a bit wheel-reinventish.

(NB that I don't want to instroduce use of automake into what is
currently a simple "upstream" Makefile; if it comes to that I would
prefer just to write my own rules for this.)

1(a). While looking at the debconf source package i18n make rules I
saw it used a program `remove-potcdate' to avoid needless updates to
the pot file. Should I really copy this (trivial) script, from
src:debconf into src:dgit, along with the substance of the make
rules which invoke it ?



2. I am unsure of the best layout of the .pot, .po, po4a, etc., files.

The convention I saw in src:debconf was to have a directory `po'
containing a single `debcconf.pot', all the message translations
LANG.po, and the corresponding Makefile and script machinery. I
dislike the idea of mixing up files edited by translators with make
machinery, but I can tolerate it if it's conventional and would
disturb people if I did it differently.

In src:debconf I also saw po4a in use. The translations were all in
doc/man/po4a/po/LANG.po, and there was also
doc/man/po4a/add_LANG/addendum.man.LANG. This all seemed a bit ad
hoc.

Is there a standard layout ? See also my next question, which may
influence the answer to this one.

Relatedly, how do automatic translation coversge tools (we have those
I think?) deal with the variety of different possible layouts ?


3. I am not sure how to divide up my translation inputs (pot files).

My single source package generates two binary packages. The two
binary packages are rather different; they perform different roles
(although they work well together) and have different (but
overlapping) audiences.

This might reasonably influence the way the messages from the two
packages (really, the two programs) are translated. So maybe I should
have two .pot files for the two sets of messages.

But the programs share a small set of library code. The library code
does not have many messages, but there are some. These messages
should be translated only once. So if I split it up, there would have
to be *three* .pot files for messages: dgit, git-debrebase and common.

(I think I can use tools like xgettext and msgcat, with appropriate
make runes, to handle any arbitrary organisation of .pot files that I
decide on.)

The need for splitting up is perhaps more acute for the documentation.
I will use po4a for that. (po4a has a powerful system for handling
almost arbitrarily strange layouts.)

The git-debrebse package has its own data model and conceptual model,
and its documentation is carefully written to talk about that in the
right terms. Additionally, perhaps it is useful for a translator to
know whether a string they are translating is part of a reference
manual or a tutorial.

But src:debconf does not split like this so maybe it is not useful ?
Or maybe it is even harmful because it might involve duplicating
certain "framework" parts or something ?


4. Terminology in translations.

As I say, one of the two packages has a specific conceptual model.
Yhat has its own terminology, which is defined in a section 5 manpage.
It is important that if and when this is translated, thought is given
to what translated names to give for each of the English terms; and
that this settled terminology is then used consistenty throughout all
of the documentation.

Also, the terminology appears, in some cases, as protocol elements
(which are in text and amy be displayed to the user). These obviously
cannot be translated or things will break. So I think, ideally, when
the terms are defined in the section 5 manpage, the English words
should be stated alongside the translated ones.

Can I (should I) leave a note to translators about these issues ?
The relevant documents are in perl pod format.


5. Translation priority

Obviously translators are volunteers and will work on what they feel
is most important. But I think some parts are much more important to
translate than others:

These tools, particularly dgit, are useful within Debian but also,
IMO, extremely useful outside it. Different people will use it in
different ways.

This is reflected in the documentation. Some of the documentation is
aimed at users and downstreams; whereas some is aimed primarily at
Debian maintainers for whom it is less important to have translations
since much of the rest of their work has to be done in English.

Is there a sensible way to inform translators about this kind of
thing, so that they can spend their time wisely ? I think maybe I
would like to tag some documents as high, medium, or low priority, or
something.


6. Committing the .pot file

AFAICT it is conventional for the .pot file(s), generated
automatically from the source code with xgettext, to included in
source packages, git repos, etc.

That seems odd. What is the reason for this ? Can I sensibly diverge
from this and expect translators etc. to run a build rune to get the
.pot files ?


I was surprised not to find answers to my questions in the
documentation for gettext, etc. Am I missing some best practice
guide ?

All advice and opinions gratefully appreciated.

Thanks,
Ian.

[Jacob Sparre Andersen]

Ian Jackson wrote:

[just answering one of your questions]

Post by Ian Jackson
6. Committing the .pot file

You can't expect translators to be ready to run any commands (or even to
have the required tools installed) to generate the .pot file(s).

But it is still (in my opinion) a bad idea to commit the .pot file. You
should rather include it with other build output, and make sure it is
archived in an easy-to-find location for your translators, so they don't
have to figure out how to build the program (or just the .pot file)
before they can start translating.
Greetings,

Jacob

[Helge Kreutzmann]

Hello Ian,
answering at least partially from a translators and package
maintainers view, who also i18n his programm (albeit on a much smaller
scale).

Post by Ian Jackson
Hi. I hope this is a suitable list for my question. If not, please
direct me elsewhere...

At least some experts are on this list, so I belive it is a good
start.

Post by Ian Jackson
I am doing the i18n for a package (src:dgit) which I think it will be
useful to translate (at least, much of it). It's a Debian native
package containing mostly perl scripts.
1. There doesn't seem to be any standard set of Makefile machiner to
include, or anything. Do I really have to write my own make rules to
run xgettext etc. ? I looked at the debconf source package, which
seemed like it would be a good example, and it had its own rules. I
can write my own rules if that is best; they're not huge. It just
seemed a bit wheel-reinventish.

You might have a look at dpkg / apt as well, but I agree that there
does not seem to be a plug in ready to use make file. But on the other
hand I did not find po4a overly complicated and looking at good
examples made me write the necessary files rather quickly, especially
using the man pages of po4a.

Post by Ian Jackson
(NB that I don't want to instroduce use of automake into what is
currently a simple "upstream" Makefile; if it comes to that I would
prefer just to write my own rules for this.)

My most work come from exactly this, so your use case appears even
simpler.

Post by Ian Jackson
2. I am unsure of the best layout of the .pot, .po, po4a, etc., files.
The convention I saw in src:debconf was to have a directory `po'
containing a single `debcconf.pot', all the message translations
LANG.po, and the corresponding Makefile and script machinery. I
dislike the idea of mixing up files edited by translators with make
machinery, but I can tolerate it if it's conventional and would
disturb people if I did it differently.

This is the standard layout. If a new translators picks appears (s)he
will look for the pot file, copy it over to, say de.po, and start
working on it. (I'm not an expert on tools like weblate, but they
probably do similar things for the online interfaces).

Post by Ian Jackson
In src:debconf I also saw po4a in use. The translations were all in
doc/man/po4a/po/LANG.po, and there was also
doc/man/po4a/add_LANG/addendum.man.LANG. This all seemed a bit ad
hoc.
Is there a standard layout ? See also my next question, which may
influence the answer to this one.

This is the way it is designed, but you can do it differently, e.g.
dpkg has a single man/po directory with all .po and .add files in it.

Post by Ian Jackson
Relatedly, how do automatic translation coversge tools (we have those
I think?) deal with the variety of different possible layouts ?

Hopefully people with background on our i18n machinery can answer this
in more detail.

Post by Ian Jackson
3. I am not sure how to divide up my translation inputs (pot files).
My single source package generates two binary packages. The two
binary packages are rather different; they perform different roles
(although they work well together) and have different (but
overlapping) audiences.
This might reasonably influence the way the messages from the two
packages (really, the two programs) are translated. So maybe I should
have two .pot files for the two sets of messages.
But the programs share a small set of library code. The library code
does not have many messages, but there are some. These messages
should be translated only once. So if I split it up, there would have
to be *three* .pot files for messages: dgit, git-debrebase and common.

From a translators POV try to avoid too many pot files. Usually
translation teams are understaffed, so if you really must split the
files, do so by importance and label the "level 1", "level 2" or "prio
1" and "prio 2". This will guide translators. But if you want
consistency, have a few (or even a single file) might be best.

Post by Ian Jackson
(I think I can use tools like xgettext and msgcat, with appropriate
make runes, to handle any arbitrary organisation of .pot files that I
decide on.)

Yes.

Post by Ian Jackson
The need for splitting up is perhaps more acute for the documentation.
I will use po4a for that. (po4a has a powerful system for handling
almost arbitrarily strange layouts.)
The git-debrebse package has its own data model and conceptual model,
and its documentation is carefully written to talk about that in the
right terms. Additionally, perhaps it is useful for a translator to
know whether a string they are translating is part of a reference
manual or a tutorial.

Giving context information to translators is always good. You can add
annotations via po4a, so guiding translators is appreciated.

Post by Ian Jackson
But src:debconf does not split like this so maybe it is not useful ?
Or maybe it is even harmful because it might involve duplicating
certain "framework" parts or something ?

Try to avoid duplicating strings, this is really bad for translators.
Splitting translations might make sense, as it is usually much larger.
If a translator encounters a 100 string file for an important tool,
(s)he might start and finish much quicker (including review on the
translation list) than say for a 500 string file.

Post by Ian Jackson
4. Terminology in translations.
As I say, one of the two packages has a specific conceptual model.
Yhat has its own terminology, which is defined in a section 5 manpage.
It is important that if and when this is translated, thought is given
to what translated names to give for each of the English terms; and
that this settled terminology is then used consistenty throughout all
of the documentation.
Also, the terminology appears, in some cases, as protocol elements
(which are in text and amy be displayed to the user). These obviously
cannot be translated or things will break. So I think, ideally, when

Add hints to translators, what to translate. Please note, however, if
your programm gets i18n, some strings might get translated, e.g. if
you query a user with a yes/no question in this case the answer might
be in the language of the user.

Post by Ian Jackson
the terms are defined in the section 5 manpage, the English words
should be stated alongside the translated ones.

I like the idea.

Post by Ian Jackson
Can I (should I) leave a note to translators about these issues ?
The relevant documents are in perl pod format.

Yes, please do.

Post by Ian Jackson
5. Translation priority
Obviously translators are volunteers and will work on what they feel
is most important. But I think some parts are much more important to
These tools, particularly dgit, are useful within Debian but also,
IMO, extremely useful outside it. Different people will use it in
different ways.
This is reflected in the documentation. Some of the documentation is
aimed at users and downstreams; whereas some is aimed primarily at
Debian maintainers for whom it is less important to have translations
since much of the rest of their work has to be done in English.
Is there a sensible way to inform translators about this kind of
thing, so that they can spend their time wisely ? I think maybe I
would like to tag some documents as high, medium, or low priority, or
something.

If you annote the initial strings with this information ("the target
audience of this is a Debian developer / a random user") then I belive
translation teams can and will handle the priority by themselfs. But
note that some translator simply like the programm and will translate
everything irrespective of priority.

Post by Ian Jackson
6. Committing the .pot file
AFAICT it is conventional for the .pot file(s), generated
automatically from the source code with xgettext, to included in
source packages, git repos, etc.
That seems odd. What is the reason for this ? Can I sensibly diverge
from this and expect translators etc. to run a build rune to get the
.pot files ?

Please don't. Translators are not developers. They usually will not
run any build tools. Also online programs, l10n monitor scripts etc.
will usually not work without the pot file. Simply update the pot file
whenever your strings change, the rest is covered in the traditional
translation machinery.

This might not be the best way, but this is the working way.

Post by Ian Jackson
I was surprised not to find answers to my questions in the
documentation for gettext, etc. Am I missing some best practice
guide ?
All advice and opinions gratefully appreciated.

I hope the answers help you. If you need more information, do not
hesitate to ask.

Greetings

Helge

[Ian Jackson]

Post by Helge Kreutzmann
answering at least partially from a translators and package
maintainers view

Thanks for all the helpful advice. Most of it I will simply take on
board and implement, so I have snipped those parts of this mail. I'll
reply only with the bits I had further questions/comments on.

Post by Helge Kreutzmann

Post by Ian Jackson
Relatedly, how do automatic translation coversge tools (we have those
I think?) deal with the variety of different possible layouts ?

Hopefully people with background on our i18n machinery can answer this
in more detail.

In the absence of an answer I guess I will try to keep the layout as
standard as possible.

Post by Helge Kreutzmann

Post by Ian Jackson
3. I am not sure how to divide up my translation inputs (pot files).

...

Post by Helge Kreutzmann
From a translators POV try to avoid too many pot files. Usually
translation teams are understaffed, so if you really must split the
files, do so by importance and label the "level 1", "level 2" or "prio
1" and "prio 2". This will guide translators. But if you want
consistency, have a few (or even a single file) might be best.

I think this means I should have one .pot file for all the messages.

Post by Helge Kreutzmann

Post by Ian Jackson
The git-debrebse package has its own data model and conceptual model,
and its documentation is carefully written to talk about that in the
right terms. Additionally, perhaps it is useful for a translator to
know whether a string they are translating is part of a reference
manual or a tutorial.

Giving context information to translators is always good. You can add
annotations via po4a, so guiding translators is appreciated.

That sounds very useful but I didn't find that feature. I have looked
in po4a(7) and po4a(1p). Can you point to an example where this has
been done, and/or some reference documentation ?

Post by Helge Kreutzmann
Try to avoid duplicating strings, this is really bad for translators.
Splitting translations might make sense, as it is usually much larger.
If a translator encounters a 100 string file for an important tool,
(s)he might start and finish much quicker (including review on the
translation list) than say for a 500 string file.

Right. (I take it that when you say "Splitting translations might
make sense", by "translations" you mean "translation of documents" as
opposed to "translation of messages".)

Post by Helge Kreutzmann

Post by Ian Jackson
5. Translation priority

...

Post by Helge Kreutzmann
If you annote the initial strings with this information ("the target
audience of this is a Debian developer / a random user") then I belive
translation teams can and will handle the priority by themselfs. But
note that some translator simply like the programm and will translate
everything irrespective of priority.

Right, see my question above.

Post by Helge Kreutzmann

Post by Ian Jackson
6. Committing the .pot file

...

Post by Helge Kreutzmann

Post by Ian Jackson
That seems odd. What is the reason for this ? Can I sensibly diverge
from this and expect translators etc. to run a build rune to get the
.pot files ?

Please don't. [...]

OK. In which context...

Post by Helge Kreutzmann
You can't expect translators to be ready to run any commands (or even to
have the required tools installed) to generate the .pot file(s).

This implies that I must commit the file.

Post by Helge Kreutzmann
But it is still (in my opinion) a bad idea to commit the .pot file. You
should rather include it with other build output, and make sure it is
archived in an easy-to-find location for your translators, so they don't
have to figure out how to build the program (or just the .pot file)
before they can start translating.

I'm not sure what you mean by it being a bad idea to commit it but
that I should include it with other build outputs.

Build outputs go in the binary package. They do not appear in my
source. That is, they appear neither in my git repo, nor in the .dsc
source package.

(And git and the source package will be identical; I don't believe the
notion of some kind of intermediate source makes any kind of sense.
The Debian archive is a VCS - just a really really bad one.)

You both say the translators don't want to run `make' (or the
equivalent) to make the .pots. I obviously don't want to ship the
.pots in my .debs. Therefore the .pots must be in the source.

So I will do that. There is already one other autogenerated file in
the source, debian/tests/control.

Ian.

[Helge Kreutzmann]

Hello Ian,

Post by Ian Jackson

Post by Helge Kreutzmann

Post by Ian Jackson
3. I am not sure how to divide up my translation inputs (pot files).

...

Post by Helge Kreutzmann
From a translators POV try to avoid too many pot files. Usually
translation teams are understaffed, so if you really must split the
files, do so by importance and label the "level 1", "level 2" or "prio
1" and "prio 2". This will guide translators. But if you want
consistency, have a few (or even a single file) might be best.

I think this means I should have one .pot file for all the messages.

Yes. This ensures consistency for translators. And as messages are
usually rather short, size doesn't matter here too much.

Post by Ian Jackson

Post by Helge Kreutzmann

Post by Ian Jackson
The git-debrebse package has its own data model and conceptual model,
and its documentation is carefully written to talk about that in the
right terms. Additionally, perhaps it is useful for a translator to
know whether a string they are translating is part of a reference
manual or a tutorial.

Giving context information to translators is always good. You can add
annotations via po4a, so guiding translators is appreciated.

That sounds very useful but I didn't find that feature. I have looked
in po4a(7) and po4a(1p). Can you point to an example where this has
been done, and/or some reference documentation ?

Ok, it works for Debconf and plain PO files, see e.g. gdm3 (grep for
"Translators:").

I admit I've never used it for po4a, though it should be possible,
looking at Locale::Po4a::Po(3pm)
→ Functions to build a message catalog
→ automatic

It appears as if po4a.gettextize does not (yet?) support this. You
might want to check this with the po4a authors (its worth at least a
wishlist bug).

An alternative would be to post process the po(t) files, we do this
for the German man pages (cf. toddy / Tobias Quadthammer or the
scripts in sources of manpages-de for details).
Then you could manually insert a paragraph or a table (as comments,
before the first
msgid ""
msgstr ""

E.g like
# Translation of prog documentation to LANGUAGE
# Copyright (C) YEAR THE PACKAGE'S COPYRIGHT HOLDER
# This file is distributed under the same license as the prog package.
#
# Translators:
# Some explanation for translators
#
# Translator Name <***@adress.org>, YEAR.
msgid ""
msgstr ""

The first 4 lines you would leave untouched in the translation, as
well as all lines directly before the msgid line (there could be
several translators over time).

If you have an online document, you could point translators to it.

Post by Ian Jackson

Post by Helge Kreutzmann
Try to avoid duplicating strings, this is really bad for translators.
Splitting translations might make sense, as it is usually much larger.
If a translator encounters a 100 string file for an important tool,
(s)he might start and finish much quicker (including review on the
translation list) than say for a 500 string file.

Right. (I take it that when you say "Splitting translations might
make sense", by "translations" you mean "translation of documents" as
opposed to "translation of messages".)

Correct.

Post by Ian Jackson

Post by Helge Kreutzmann

Post by Ian Jackson
6. Committing the .pot file

...

Post by Helge Kreutzmann

Post by Ian Jackson
That seems odd. What is the reason for this ? Can I sensibly diverge
from this and expect translators etc. to run a build rune to get the
.pot files ?

Please don't. [...]

OK. In which context...

Post by Helge Kreutzmann
You can't expect translators to be ready to run any commands (or even to
have the required tools installed) to generate the .pot file(s).

This implies that I must commit the file.

Correct.

Post by Ian Jackson

Post by Helge Kreutzmann
But it is still (in my opinion) a bad idea to commit the .pot file. You
should rather include it with other build output, and make sure it is
archived in an easy-to-find location for your translators, so they don't
have to figure out how to build the program (or just the .pot file)
before they can start translating.

I'm not sure what you mean by it being a bad idea to commit it but
that I should include it with other build outputs.
Build outputs go in the binary package. They do not appear in my
source. That is, they appear neither in my git repo, nor in the .dsc
source package.
(And git and the source package will be identical; I don't believe the
notion of some kind of intermediate source makes any kind of sense.
The Debian archive is a VCS - just a really really bad one.)
You both say the translators don't want to run `make' (or the
equivalent) to make the .pots. I obviously don't want to ship the
.pots in my .debs. Therefore the .pots must be in the source.
So I will do that. There is already one other autogenerated file in
the source, debian/tests/control.

I was a little imprecise, sorry.

What I intended to state:
Please carry the pot file in your sources. Update it whenever you feel
necessary, but at least before a release, so that the tar ball
contains an up to date pot. The pot file should not be part of the deb
package, of course.

It is a good idea for old school translators like me to have a brief
description how to update the pot and po files in your source, like
make update-po
so when translators decide to work directly off your repository, they
know how to create an up to date pot file.

Greetings

Helge

[Ian Jackson]

Post by Helge Kreutzmann
Hello Ian,

Post by Ian Jackson

Post by Helge Kreutzmann
Giving context information to translators is always good. You can add
annotations via po4a, so guiding translators is appreciated.

That sounds very useful but I didn't find that feature. I have looked
in po4a(7) and po4a(1p). Can you point to an example where this has
been done, and/or some reference documentation ?

Ok, it works for Debconf and plain PO files, see e.g. gdm3 (grep for
"Translators:").

Oh, I see.

DYK where this is documented ?

I searched the whole in the GNU gettext documentation for the string
`translators:' and it has a couple of (fairly obscure) example cases,
but I didn't see a basic description of the feature.

Ian.

[Helge Kreutzmann]

Hello Ian,

Post by Ian Jackson

Post by Helge Kreutzmann

Post by Ian Jackson

Post by Helge Kreutzmann
Giving context information to translators is always good. You can add
annotations via po4a, so guiding translators is appreciated.

That sounds very useful but I didn't find that feature. I have looked
in po4a(7) and po4a(1p). Can you point to an example where this has
been done, and/or some reference documentation ?

Ok, it works for Debconf and plain PO files, see e.g. gdm3 (grep for
"Translators:").

Oh, I see.
DYK where this is documented ?

I don't know, sorry.

Post by Ian Jackson
I searched the whole in the GNU gettext documentation for the string
`translators:' and it has a couple of (fairly obscure) example cases,
but I didn't see a basic description of the feature.

Probably you would have to ask the developers.

Greetings

Helge

[Ian Jackson]

Thanks for your helpful comments earlier. I have now done much of the
work to do message translation for the dgit package. The results are
now in experimental, and can be found here:
https://browse.dgit.debian.org/dgit.git/tree/?h=debian/7.0_pre1
or with `dgit clone dgit experimental'.

I'm still working on marking up git-debrebase for message translation,
and haven't done anything about the docs. When I have done those
things, and subject to any review comments I get here, I intend to
call it 7.0 and upload to sid.

Comments welcome, particularly on the file po/README.
https://browse.dgit.debian.org/dgit.git/tree/po/README?h=debian/7.0_pre1


I am considering creating a salsa repo for translation merge requests,
by analogy with what was done for debian-policy:
https://salsa.debian.org/dbnpolicy/policy-l10n-merge-requests-here

If I do create such a repo, I will probably rebase PR branches onto my
own master, rather than using `git merge', because I prefer to make
the history more linear-looking. Would that be a problem ?

It occurs to me that maybe this kind of thing should be in a
translation teams salsa project, and a standard naming convention,
etc.

I even wonder whether it would be sensible to make some kind of
automatic dgit-based mirroring setup so that translators can work in a
uniform way, with git, on any package. Of course a translator can
just use `dgit clone' right now, and `git-send-email' or something to
file their results in the Debian BTS, but that doesn't give a pretty
web ui.


One difficulty is that I am very much in the habit of constructing my
error messages out of pieces. This is recommended against in the
gettext manual, and I understand the reasons. However, the
prescription to make each message be a whole sentence is impractical
from an implementation point of view:

Both because it's impractical to write the source code that way (since
in neither the places where the message fragments are generated, and
where they are consumed, have is there enough information to be able
write down that whole sentence); and because it would result in many
cases in a combinatorial explosion of different message strings
(sometimes with different combinations of %-substitutions etc.)

I hope that in languages where inflection and agreement are important,
translators will be willing to fudge this, and that users of my
programs (the latter being - at least sort-of - programmers) will be
able to cope with the resulting odd-sounding messages. I guess these
kind of problems are hardly new.


Regards,
Ian.

[Ian Jackson]

Post by Ian Jackson
I'm still working on marking up git-debrebase for message translation,
and haven't done anything about the docs. When I have done those
things, and subject to any review comments I get here, I intend to
call it 7.0 and upload to sid.

This is now done. The updated README is here:
https://browse.dgit.debian.org/dgit.git/tree/po/README

Suggestions, and advice or comments about the other things later in my

Post by Ian Jackson
I am considering creating a salsa repo for translation merge requests,
https://salsa.debian.org/dbnpolicy/policy-l10n-merge-requests-here
If I do create such a repo, I will probably rebase PR branches onto my
own master, rather than using `git merge', because I prefer to make
the history more linear-looking. Would that be a problem ?

...

Post by Ian Jackson
It occurs to me that maybe this kind of thing should be in a
translation teams salsa project, and a standard naming convention,
etc.

Regards,
Ian.

[Helge Kreutzmann]

Hello Ian,
full quote, as i acidentially dropped the list.

Post by Helge Kreutzmann
Hello Ian,

Post by Ian Jackson
https://browse.dgit.debian.org/dgit.git/tree/po/README

Thanks. Reading it as a translator, I like it, as it gives me a good
introduction where to start and what are the relations and priorties.

Thanks. I really appreciate your feedback (both positive and
negative). It is very helpful to have guidance from people who know
the area better.
(Was there a reason you dropped the list? If not, please do post your
response there, as I think it's likely to be helpful to others, given
the questions I am about to ask...)

No, it happened by chance.

Post by Helge Kreutzmann
I'm only missing a paragraph about minimum translation, i.e. how much
of the messages / man pages need to be translated, before the
translation is used. Is this the common 80% rule or did you change it?

This is an interesting question. I noticed while working on the po4a
machinery that there was this -t option. But I didn't have much of an
idea on what basis I ought to be setting the value.
After thinking about it a bit I set it to 50%. I would have gone
lower, but I wasn't sure if there was a good reason not to set it to
(say) 10%.
Is it very jarring or difficult for the reader, to provide a
partially-translated document ? Obviously a fully-translated document
is better. But ISTM that a partially-translated one is likely to be
better than a completely untranslated one.

As you give good guidenance like providing the original term alongside
the translated one, i completely agree in your case. This eases the
burden for translators also, as they know the result can be seen /
used earlier. (Translation resources are scarce, especially if a
review is added).

This is particularly true for documents like mine, which are very
"sectional" if you see what I mean.

Yes, I understand.

As for the messages, I'm not wrong in thinking that any translation at
all is better than none, so the po message translation machinery has
no threshold ? I mean, I just use msgmerge with no special options.

Post by Helge Kreutzmann
(And you might want to run a spellchecker over it, as there a several
typos).

Thanks for that suggestion. I will do that.

Post by Helge Kreutzmann
Start small, develop I'd say. From a translators view, who likes to
work on the repositories directly, I just would like to have a little
hassel as possible, as I know the basic git commands, but having
complex instructions for merging I would avoid, so if the machinery is
completely on the salsa side, I would not mind (sorry that I cannot
figure that out from your mail, in my use case I simply "push" the
updated file and then the maintainer does the rest).

Err, yes.

Post by Helge Kreutzmann
You may want to add a paragraph in README about commiting the translation
as well (or a pointer to where this is covered).

Right now there is no translation git repository. Nor even a tree on
salsa. The git history is provided on the dgit git server (ie, you
`dgit clone'). I think I should probably start by providing my own
tree on salsa.
I will add something to the README about committing the translation
and using salsa to send a MR.

That would be verfy helpful.

My thinking in my earlier mail was that maybe we should have a team on
salsa that has automatically-updated repos for every translatable
package and where a translator can just send a merge request.
Presumably some robot would keep these trees updated, transform merge
requests into BTS emails, and so on.

This is in principle a very interesting idea. Before starting, I would
like to point out three issues:

a) Translations are not 1:1, even within a domain like "computer
science" or "free software". Let alone that sometime you do
translate a term (let's say, the option is a filename, then
"filename" would be translated), and sometimes you don't (when
filename is the key, where an option is assigned to, oviously then
"filename" shall not be translate).

b) It is a huge tasks, requiring infrastruture, cooperation, etc. If
bubulle is still around, you might contact him, as he
(unsuccesfully, despite his *very* huge investement), tried this.

c) Only "native" packages or packages with no upstream translation
machinery could join, otherwise duplicated work would occur (e.g.
KDE, GNOME, libreoffice etc. have their own teams, there are
spanning efforts for multiple packages (cross distro)).

So yes, if it would work, it would be very welocmed, but maybe dgit
first?

Greetings

Helge

[Ian Jackson]

Post by Helge Kreutzmann
As you give good guidenance like providing the original term alongside
the translated one, i completely agree in your case. This eases the
burden for translators also, as they know the result can be seen /
used earlier. (Translation resources are scarce, especially if a
review is added).

Thanks for the guidance. I have set it to 10% and documented that
in the po/README.

Post by Helge Kreutzmann

Post by Helge Kreutzmann
(And you might want to run a spellchecker over it, as there a several
typos).

Thanks for that suggestion. I will do that.

Done, thanks :-).

Post by Helge Kreutzmann

I will add something to the README about committing the translation
and using salsa to send a MR.

That would be verfy helpful.

I have created the group and project and repo on salsa and added
some README stuff. I hope this is roughtly what you meant:
https://salsa.debian.org/dgit-team/dgit
https://salsa.debian.org/dgit-team/dgit/tree/master/po

I guess I shouldn't send a CFT (Call For Translation) just yet because
my freeze date is a way off. dgit is at the top of its pile, rather
than at the bottom, so changes can be made quite late. 8.0 (just
uploaded) has nontrivial changes and depending on my CFT (Copious Free
Time (-:) I may yet do more significant work on it.

Regards,
Ian.

[Helge Kreutzmann]

Hello Ian,

Post by Ian Jackson

Post by Helge Kreutzmann

I will add something to the README about committing the translation
and using salsa to send a MR.

That would be verfy helpful.

I have created the group and project and repo on salsa and added
https://salsa.debian.org/dgit-team/dgit
https://salsa.debian.org/dgit-team/dgit/tree/master/po

From my translators POV this looks very nice, so I would know where to
start.

Post by Ian Jackson
I guess I shouldn't send a CFT (Call For Translation) just yet because
my freeze date is a way off. dgit is at the top of its pile, rather
than at the bottom, so changes can be made quite late. 8.0 (just
uploaded) has nontrivial changes and depending on my CFT (Copious Free
Time (-:) I may yet do more significant work on it.

This is a tricky question. Translators are as developers - little time
and lots to do. And many teams have the review step, i.e. a second
translator comments and improves the translation of the first. Again,
time consuming. And as you set »--previous«, slightly outdated
translations are not lost and responsive translators might quickly
adapt many tuned strings.

Unless you intend a huge rework of strings (e.g. changing the style or
markup or tone or something) I would use podebconf-report-po(1) (yes,
this can be used for any type of po files) rather sooner than later,
so interested teams get started and you could get some translations before
the (hard) freeze. Just be polite and inform translators that strings
still might change, so teams can set priorities.

I'm currently involved in two larger translation sets for DE, so I
don't know (yet) if I have time to work on it for DE, but maybe
another translator kicks in.

Greetings

Helge

[Ian Jackson]

Post by Helge Kreutzmann
Unless you intend a huge rework of strings (e.g. changing the style or
markup or tone or something) I would use podebconf-report-po(1) (yes,
this can be used for any type of po files) rather sooner than later,

Thanks, I will do this.

The manpage suggests that it will attach the .pot files.

| podebconf-report-po can also be used to send a call for
| translations to a mailing list. In that case, the POT file will be
| attached.

Is it really appropriate to send a .pot to this mailing list like
that ? Also, because each manual is its own .pot, there are 13 .pot
files.

Regards,
Ian.

[Helge Kreutzmann]

Hello Ian,

Post by Ian Jackson
The manpage suggests that it will attach the .pot files.
| podebconf-report-po can also be used to send a call for
| translations to a mailing list. In that case, the POT file will be
| attached.
Is it really appropriate to send a .pot to this mailing list like
that ? Also, because each manual is its own .pot, there are 13 .pot
files.

If you feel this is to big or to confusing, because several pot files
exist, then use the option "--sendmessage" and explain in your e-mail
how to get the pot file(s). In this case be a little verbose, as not
all translators fluently speak git.

Greetings

Helge