Comments would make translations easier

[Moritz Baumann]

I'm currently trying to translate upstart into German. Since it is impossible to find most strings "using" upstart (everything which hasn't got anything to do with command line utilities like shutdown), some strings cannot be properly translated without taking a look at the source code, esp. those containing placeholders. Comments would definitely help a lot here!

[Scott James Remnant (Canonical) (canonical-scott)]

A significant portion of Upstart's source code *is* comments? Have you even looked at it?

[Moritz Baumann (mo42)]

You completely misunderstood my problem. ;) The source code is perfectly readable, of course. The problem is that difficult *strings* are not commented. Most translators don't know any C! Normally we wouldn't search for every string in the source files and just translate it in Rosetta, which results in a very bad translation if the strings are not commented at all.

[Scott James Remnant (Canonical) (canonical-scott)]

On Mon, 2010-02-15 at 15:03 +0000, Moritz Baumann wrote:

> You completely misunderstood my problem. ;) The source code is perfectly
> readable, of course. The problem is that difficult *strings* are not
> commented. Most translators don't know any C! Normally we wouldn't
> search for every string in the source files and just translate it in
> Rosetta, which results in a very bad translation if the strings are not
> commented at all.
>
What difficult strings?

You're not providing any examples here.

 status incomplete

Scott
--
Have you ever, ever felt like this?
Had strange things happen? Are you going round the twist?

[Moritz Baumann (mo42)]

To name some examples:

"stop", "start", "respawn", "pre-start", etc.: Should they even be translatable? Context?
"Failed to spawn %s %s process: %s": What is missing here?

Of course it's the translators job to look up the terminology and what the program does, but then the rest should be self-explanatory. So whenever the context is not clear if you only see the string, please give us a hint.

If it helps, I could create a list of all problematic strings, now that I'm re-translating it anyway.

[Scott James Remnant (Canonical) (canonical-scott)]

On Mon, 2010-02-15 at 15:50 +0000, Moritz Baumann wrote:

> To name some examples:
>
> "stop", "start", "respawn", "pre-start", etc.: Should they even be translatable? Context?
>
So go look at the context then.

The source is full of documentation about what these mean.

> "Failed to spawn %s %s process: %s": What is missing here?
>
Look at the code?

 /* Return non-temporary error condition */
 nih_warn (_("Failed to spawn %s %s process: %s"),
    job_name (job), process_name (process),
    err->message);

This makes it very clear that those are a job name, a process name and
the error message.

> Of course it's the translators job to look up the terminology and what
> the program does, but then the rest should be self-explanatory. So
> whenever the context is not clear if you only see the string, please
> give us a hint.
>
I'm not interested in doing that; you're not expected to be able to
translate by only seeing the strings - you're expected to read the
context as well - that's why you have the filename and line number.

 status invalid

Scott
--
Have you ever, ever felt like this?
Had strange things happen? Are you going round the twist?

[Moritz Baumann (mo42)]

> I'm not interested in doing that; you're not expected to be able to
> translate by only seeing the strings - you're expected to read the
> context as well - that's why you have the filename and line number.

I offered to do that work for you, so I don't really understand why you're
refusing to add comments before some of the translatable strings so that they
show up in the po files in the end. Reading the source code is not part of our
normal workflow.

Moritz

[Scott James Remnant (Canonical) (canonical-scott)]

On Mon, 2010-02-15 at 17:07 +0000, Moritz Baumann wrote:

> > I'm not interested in doing that; you're not expected to be able to
> > translate by only seeing the strings - you're expected to read the
> > context as well - that's why you have the filename and line number.
>
> I offered to do that work for you, so I don't really understand why you're
> refusing to add comments before some of the translatable strings so that they
> show up in the po files in the end. Reading the source code is not part of our
> normal workflow.
>
Because it makes reading the source code harder for developers.

I don't want it polluted with information for translators that *has* to
be on the line before every string, just because they won't read the
source code which is already perfectly well commented.

Scott
--
Have you ever, ever felt like this?
Had strange things happen? Are you going round the twist?

[David Planella (dpm)]

Hi,

Moritz is referring to extracted comments [1].

These are simply comments put on the line of code preceeding the translatable string by developers to ease the work of translators, which then get extracted and put into the POT file so they get some context information and they do not have to look into the source code.

Looking at source code files should only be the last resort, as there is a large part of the translations community which is not technically oriented and dealing with source code files is not in their area of expertise.

The point is to ease the entry barrier to contributors, which is why this functionality is present in the gettext PO file format and also supported in Launchpad (see [2] for an example)

For translatable strings which might be ambiguous or might need more context, it is customary to simply add a comment providing this context in the form of (see the linked branch for an example):

  /* TRANSLATORS: here you've got some context on this nasty string */

In our translation team we've actually had the same problem with some of these upstart strings, and I believe having some context would make translation work much easier.

Moritz, do you think you could identify which strings need context and provide some fixes?

Scott, would you accept Moritz's fixes if he were to provide a branch with these additional context comments? (I've provided some already in the one I've linked to the bug).

Thanks!

[1] http://www.gnu.org/software/gettext/manual/gettext.html#PO-Files
[2] https://translations.edge.launchpad.net/gdebi/trunk/+pots/gdebi/ca/77/+translate

[Scott James Remnant (Canonical) (canonical-scott)]

On Mon, 2010-02-15 at 18:00 +0000, David Planella wrote:

> Scott, would you accept Moritz's fixes if he were to provide a branch
> with these additional context comments? (I've provided some already in
> the one I've linked to the bug).
>
I would not.

As I said, I believe this would make the source code harder to read and
maintain for developers,

Scott
--
Have you ever, ever felt like this?
Had strange things happen? Are you going round the twist?

[Moritz Baumann (mo42)]

You obviously don't know much about the work we do an who we are, so please let me clarify one thing: We're not refusing to take a source code because we're too lazy, that's just not the way translating Ubuntu works … Firstly, because we're not used to reading source code and many of us won't understand it (Many people become translators because their knowledge doesn't allow them to contribute to Ubuntu as a developer. We're *not* developers!) and secondly because it'd take at least ten times as long to translate this way. (We're already happy if we manage to translate the most important packages correctly until the translation deadline at the moment.)

I don't believe that 25 lines of comments would make a program with thousands (ten thousands?) of lines of source code harder to maintain or read. I understand explaining difficult strings to translators is not exactly what you care about a lot as a developer and may be a bit annoying, but we need such information to be present.

If you want us to translate upstart properly, please add comments for some strings or let me add them. Otherwise most translations will be incomplete, non-existent or simply wrong.

[David Planella (dpm)]

It seems we've got a bit of a disconnect here.

We're keen to build the best software and the best translations around, and for this to happen we simply need some additional comments to unblock the work of translators.

This type of translator comments are common in all internationalized software projects, and Moritz is offering to do the work of identifying the few strings where they might be needed (I will happily provide a branch with the changes myself, if necessary).

I think the level of change in the code is minimal, while the benefit for translators and users in all languages can be huge.

[Moritz Baumann (mo42)]

Even when reading through the source code, some strings are not that obvious (after reading through process.c I had to change all strings containing the "process name"; I hadn't suspected it to be something like "pre-start") …

BTW: I just noticed that the word "process" in the output of "initctl status" is not translatable. Just as a little anntotation, really not worth opening a bug report for it.

[Scott James Remnant (Canonical) (canonical-scott)]

On Tue, 2010-02-23 at 23:02 +0000, Moritz Baumann wrote:

> Even when reading through the source code, some strings are not that
> obvious (after reading through process.c I had to change all strings
> containing the "process name"; I hadn't suspected it to be something
> like "pre-start") …
>
That's a process name. Read init/process.h

> BTW: I just noticed that the word "process" in the output of "initctl
> status" is not translatable. Just as a little anntotation, really not
> worth opening a bug report for it.
>
That's a valid bug. Please file it.

Scott
--
Have you ever, ever felt like this?
Had strange things happen? Are you going round the twist?