Where to contribute manual translations ? (Re: Emacs-devel Digest, Vol 238, Issue 29)

Where to contribute manual translations ? (Re: Emacs-devel Digest, Vol 238, Issue 29)

[Jean-Christophe Helary]

> On Dec 29, 2023, at 2:00, emacs-devel-request@gnu.org wrote:

> Message: 1
> Date: Wed, 27 Dec 2023 21:14:06 +0000
> From: Vincent Belaïche <vincent.b.1@hotmail.fr>
> To: emacs-devel <emacs-devel@gnu.org>
> Subject: Where to contribute manual translations ?
> Message-ID:
> 	<PAXP192MB1608F5D8D0A89A5571C67D07849FA@PAXP192MB1608.EURP192.PROD.OUTLOOK.COM>
> 
> 
> Hello,
> 
> Where is the right place to contribute a translation to French of the SES manual ?
> Is it there : https://savannah.nongnu.org/projects/emacsdoc-fr
> French GNU Emacs manual - Summary [Savannah]<https://savannah.nongnu.org/projects/emacsdoc-fr>
> Savannah is a central point for development, distribution and maintenance of free software, both GNU and non-GNU.
> savannah.nongnu.org

There have been many attempts at translating the manuals.

One was organized by traduc.org. I ended up "in charge" of it.

I moved the project to chapril / sr.ht a few years ago to easily include translators. The translation evolves slowly by it is also used for technical translation master student internships.

https://forge.chapril.org/brandelune/documentation_emacs/

The sources are hosted on sr.ht.

https://git.sr.ht/~brandelune/emacs_documentation_repository

> Another question : how to internationalize docstrings ? IMHO it would be great if the docstring could have some info manual anchor in it, and one could display it from the currently selected language manual. Besides, reading docstring from manual via some anchor is basically what Calc does with some kitchen tricks.

Eli answered that.


> Message: 17
> Date: Thu, 28 Dec 2023 07:32:08 -0800
> From: Stefan Kangas <stefankangas@gmail.com>
> To: Eli Zaretskii <eliz@gnu.org>, Vincent Belaïche
> 	<vincent.b.1@hotmail.fr>
> Cc: emacs-devel@gnu.org
> Subject: Re: Where to contribute manual translations ?
> Message-ID:
> 	<CADwFkm=3UkocaW-wDg6KXOeR9zLQmYBh9Vn+tc76NnyBum+FrQ@mail.gmail.com>
> Content-Type: text/plain; charset="UTF-8"
> 
> It's also perhaps somewhat overblown given that we only expect to have a
> very small number of translated manuals for the foreseeable future.[1]
> 
[...]
> 
> Footnotes:
> [1]  I'm not aware of anyone else working on translating our manuals.

French is slowly ongoing. I seem to remember that Japanese has a book version but it's getting old.



-- 
Jean-Christophe Helary @jchelary@emacs.ch
https://traductaire-libre.org
https://mac4translators.blogspot.com
https://sr.ht/~brandelune/omegat-as-a-book/

Re: Where to contribute manual translations ? (Re: Emacs-devel Digest, Vol 238, Issue 29)

[Jean-Christophe Helary]

> On Dec 29, 2023, at 9:24, Jean-Christophe Helary <jean.christophe.helary@traductaire-libre.org> wrote:
> 
>> On Dec 29, 2023, at 2:00, emacs-devel-request@gnu.org wrote:
> 
>> Message: 1
>> Date: Wed, 27 Dec 2023 21:14:06 +0000
>> From: Vincent Belaïche <vincent.b.1@hotmail.fr>
>> To: emacs-devel <emacs-devel@gnu.org>
>> Subject: Where to contribute manual translations ?
>> Message-ID:
>> 	<PAXP192MB1608F5D8D0A89A5571C67D07849FA@PAXP192MB1608.EURP192.PROD.OUTLOOK.COM>
>> 
>> 
>> Hello,
>> 
>> Where is the right place to contribute a translation to French of the SES manual ?
>> Is it there : https://savannah.nongnu.org/projects/emacsdoc-fr
>> French GNU Emacs manual - Summary [Savannah]<https://savannah.nongnu.org/projects/emacsdoc-fr>
>> Savannah is a central point for development, distribution and maintenance of free software, both GNU and non-GNU.
>> savannah.nongnu.org
> 
> There have been many attempts at translating the manuals.
> 
> One was organized by traduc.org. I ended up "in charge" of it.
> 
> I moved the project to chapril / sr.ht a few years ago to easily include translators. The translation evolves slowly by it is also used for technical translation master student internships.
> 
> https://forge.chapril.org/brandelune/documentation_emacs/
> 
> The sources are hosted on sr.ht.
> 
> https://git.sr.ht/~brandelune/emacs_documentation_repository

I also made a presentation at EmacsConf 2021 on the subject:
https://emacsconf.org/2021/talks/omegat/

If you're interested in joining this effort, it is extremely "horizontal" → you don't have to do anything in particular. If you need to discuss terminology issues, I just created a dedicated mailing list:

https://lists.sr.ht/~brandelune/documentation_emacs

And I also created a tracker for translation/technical issues:
https://todo.sr.ht/~brandelune/documentation_emacs

You can also not join this project and that's also totally fine.

>> Another question : how to internationalize docstrings ? IMHO it would be great if the docstring could have some info manual anchor in it, and one could display it from the currently selected language manual. Besides, reading docstring from manual via some anchor is basically what Calc does with some kitchen tricks.
> 
> Eli answered that.

There is also a different issue, that comes before translation, it is fixing user facing strings, so that they can eventually be translated one day. I also made a presentation on that at EmacsConf 2022:
https://emacsconf.org/2022/talks/localizing/




-- 
Jean-Christophe Helary @jchelary@emacs.ch
https://traductaire-libre.org
https://mac4translators.blogspot.com
https://sr.ht/~brandelune/omegat-as-a-book/

Re: Where to contribute manual translations ? (Re: Emacs-devel Digest, Vol 238, Issue 29)

[Eli Zaretskii]

> Date: Fri, 29 Dec 2023 01:23:40 +0000
> From: Jean-Christophe Helary <jean.christophe.helary@traductaire-libre.org>
> Cc: vincent.b.1@hotmail.fr, stefankangas@gmail.com, eliz@gnu.org
> 
> >> Another question : how to internationalize docstrings ? IMHO it would be great if the docstring could have some info manual anchor in it, and one could display it from the currently selected language manual. Besides, reading docstring from manual via some anchor is basically what Calc does with some kitchen tricks.
> > 
> > Eli answered that.
> 
> There is also a different issue, that comes before translation, it is fixing user facing strings, so that they can eventually be translated one day. I also made a presentation on that at EmacsConf 2022:
> https://emacsconf.org/2022/talks/localizing/

I believe this issue was also raised in the discussions whose pointers
I provided.  AFAIR, this issue is a much harder one, since
manipulating such strings is pervasive in Emacs, and mostly in Lisp,
not in C.

Re: Where to contribute manual translations ? (Re: Emacs-devel Digest, Vol 238, Issue 29)

[Emanuel Berg]

Jean-Christophe Helary wrote:

> I also made a presentation at EmacsConf 2021 on the subject:
> https://emacsconf.org/2021/talks/omegat/

Did you say that the French and English languages, in terms of
technology and science, are virtually identical?

-- 
underground experts united
https://dataswamp.org/~incal

Re: Where to contribute manual translations ? (Re: Emacs-devel Digest, Vol 238, Issue 29)

[Jean-Christophe Helary]

> On Dec 29, 2023, at 15:48, Eli Zaretskii <eliz@gnu.org> wrote:
> 
>> Date: Fri, 29 Dec 2023 01:23:40 +0000
>> From: Jean-Christophe Helary <jean.christophe.helary@traductaire-libre.org>
>> Cc: vincent.b.1@hotmail.fr, stefankangas@gmail.com, eliz@gnu.org
>> 
>>>> Another question : how to internationalize docstrings ? IMHO it would
>>>> be great if the docstring could have some info manual anchor in it, and
>>>> one could display it from the currently selected language manual.
>>>> Besides, reading docstring from manual via some anchor is basically
>>>> what Calc does with some kitchen tricks.

>> Eli answered that.

>> There is also a different issue, that comes before translation, it is 
>> fixing user facing strings, so that they can eventually be translated 
>> one day. I also made a presentation on that at EmacsConf 2022:
>> https://emacsconf.org/2022/talks/localizing/
> 
> I believe this issue was also raised in the discussions whose pointers
> I provided.

You’re correct.

> AFAIR, this issue is a much harder one, since manipulating such strings 
> is pervasive in Emacs, and mostly in Lisp, not in C.

My experience with package.el, as I suggested in the presentation, is
that knowledge of Emacs Lisp can be obtained while checking the
strings. There are not that many functions that act on strings, so it’s
relatively easy to see what’s going on in the code and how the strings
are produced.

The slightly more difficult part is to fix the strings so that even if
there is a little redundancy, there are not smart tricks on language
“objects” (like “concatenate an s if such variable is bigger than 1”),
because that involves writing some real and correct elisp :)

But it’s a fun and very practical way to learn some parts of Elisp.

As for creating a process for actually localizing the strings and
displaying them in the locale language, you are right to say that we
concluded that it was a much harder issue, since we’d have to come up
with a lisp-specific system, if my memory is correct.

-- 
Jean-Christophe Helary @jchelary@emacs.ch
https://traductaire-libre.org
https://mac4translators.blogspot.com
https://sr.ht/~brandelune/omegat-as-a-book/

RE: Where to contribute manual translations ? (Re: Emacs-devel Digest, Vol 238, Issue 29)

[Vincent Belaïche]

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

Dear Jean-Christophe,

I had a look at your git repo, and I also watched your presentation about OmegaT. I realize that all the manual translations that you have are po files that are output by OmegaT as a sequence of individual segment translations. I understand that some tool will then reassemble those segment to rebuild the Texinfo file, that can then be compiled to the usuer manuel.

My translation of SES manual to French is a « hand-made » translation (as opposed to computer-aided), so it is a plain Texinfo file which I directly edited with an editor (it was Emacs, but any editor, and even MSWord used as a text editor could have been used). Therefore I am not sure that your repo is the best place for me. For the time being I will therefore have it on the Emacs repo, when the conversation here converges on the right place and name.

I don't know how you can get my translation and use it in your OmegaT framework as the splitting into segments + segment naming is not done. Also, I am not sure that I want to install and learn how to use OmegaT, as I am not a professional translator, and my aim was not so much as to produce a translation (although I have no doubt that it will be useful), but the side products of translating, that is improve the manual quality and my knowledge and understanding. That is the same reason for which I translated to French the Unofficial LaTeX manual, that allowed plenty of minor improvements on the manual (both English & French versions).

   Vincent.
________________________________
De : Jean-Christophe Helary <jean.christophe.helary@traductaire-libre.org>
Envoyé : vendredi 29 décembre 2023 15:21
À : Eli Zaretskii <eliz@gnu.org>
Cc : emacs-devel@gnu.org <emacs-devel@gnu.org>; vincent.b.1@hotmail.fr <vincent.b.1@hotmail.fr>; stefankangas@gmail.com <stefankangas@gmail.com>
Objet : Re: Where to contribute manual translations ? (Re: Emacs-devel Digest, Vol 238, Issue 29)



> On Dec 29, 2023, at 15:48, Eli Zaretskii <eliz@gnu.org> wrote:
>
>> Date: Fri, 29 Dec 2023 01:23:40 +0000
>> From: Jean-Christophe Helary <jean.christophe.helary@traductaire-libre.org>
>> Cc: vincent.b.1@hotmail.fr, stefankangas@gmail.com, eliz@gnu.org
>>
>>>> Another question : how to internationalize docstrings ? IMHO it would
>>>> be great if the docstring could have some info manual anchor in it, and
>>>> one could display it from the currently selected language manual.
>>>> Besides, reading docstring from manual via some anchor is basically
>>>> what Calc does with some kitchen tricks.

>> Eli answered that.

>> There is also a different issue, that comes before translation, it is
>> fixing user facing strings, so that they can eventually be translated
>> one day. I also made a presentation on that at EmacsConf 2022:
>> https://emacsconf.org/2022/talks/localizing/
>
> I believe this issue was also raised in the discussions whose pointers
> I provided.

You’re correct.

> AFAIR, this issue is a much harder one, since manipulating such strings
> is pervasive in Emacs, and mostly in Lisp, not in C.

My experience with package.el, as I suggested in the presentation, is
that knowledge of Emacs Lisp can be obtained while checking the
strings. There are not that many functions that act on strings, so it’s
relatively easy to see what’s going on in the code and how the strings
are produced.

The slightly more difficult part is to fix the strings so that even if
there is a little redundancy, there are not smart tricks on language
“objects” (like “concatenate an s if such variable is bigger than 1”),
because that involves writing some real and correct elisp :)

But it’s a fun and very practical way to learn some parts of Elisp.

As for creating a process for actually localizing the strings and
displaying them in the locale language, you are right to say that we
concluded that it was a much harder issue, since we’d have to come up
with a lisp-specific system, if my memory is correct.

--
Jean-Christophe Helary @jchelary@emacs.ch
https://traductaire-libre.org
https://mac4translators.blogspot.com
https://sr.ht/~brandelune/omegat-as-a-book/


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

Re: Where to contribute manual translations ? (Re: Emacs-devel Digest, Vol 238, Issue 29)

[Jean-Christophe Helary]

Hello Vincent,

> On Dec 30, 2023, at 7:58, Vincent Belaïche <vincent.b.1@hotmail.fr> wrote:
> 
> Dear Jean-Christophe,
> 
> I had a look at your git repo, and I also watched your presentation about OmegaT. I realize that all the manual translations that you have are po files that are output by OmegaT as a sequence of individual segment translations. I understand that some tool will then reassemble those segment to rebuild the Texinfo file, that can then be compiled to the usuer manuel.

I use po4a. po4a is a tool developed to help translators handle documents that are often updated. A lot of free documentation translations are made with po4a.

po4a’s workflow is similar to gettext in terms of converting the source files to po, updating the translations, converting back the po files to the source format.

In our case we use the texinfo → po → texinfo conversion allowed by po4a.
(There is a special case for the org manual.)

As you know, Emacs evolves a lot, and diffing the sources to see what has changed is not practical when it comes to translating, because it is not trivial to locate the position of a source diff in the translated document.

po4a helps with that because the po format is a list of bilingual chunks of the original document. When sentences have been added to the source or have been slightly modified, po4a finds them and creates a monolingual chunk that the translator will have to translate.

And then, po4a converts back the chunks into the original source file, ready for compilation.

> My translation of SES manual to French is a « hand-made » translation (as opposed to computer-aided), so it is a plain Texinfo file which I directly edited with an editor (it was Emacs, but any editor, and even MSWord used as a text editor could have been used).

Anything that happens on a computer is “computer aided” :) You just decide how much aid you force the computer to give you :)

For relatively stable documents such as books, a text editor is enough, and you can use separate documents to handle terminology, etc.

OmegaT is like a small IDE for translators. It automatically checks the terminology as you enter a new chunk, it checks for previously translated similar chunks, it checks technical errors (texi tags for ex., defined as regex), etc.

> Therefore I am not sure that your repo is the best place for me. For the time being I will therefore have it on the Emacs repo, when the conversation here converges on the right place and name.

“My” repo is just a workshop. The end product is intended to be part of the Emacs distribution in a way or another.

> I don't know how you can get my translation and use it in your OmegaT framework as the splitting into segments + segment naming is not done.

I know :)

It’s a process called “aligning” translations, which means associating chunks of the source document with chunks of the target document and thus creating the bilingual (translated) chunks that I mentioned above.

po4a creates the chunks from your texinfo file, and OmegaT takes the information in that file and associates it to the original English texinfo file. 

And you end up with a list of chunks that can be used in OmegaT.

> Also, I am not sure that I want to install and learn how to use OmegaT, as I am not a professional translator, and my aim was not so much as to produce a translation (although I have no doubt that it will be useful), but the side products of translating, that is improve the manual quality and my knowledge and understanding.

It’s a very good idea. Translators are indeed proofreaders and can detect a lot of issues in the original documents.

OmegaT is not a tool limited to professional translators. It is used in many free software communities in many language environments. Its basic use is pretty straightforward and really helps maintain consistency of translation over very large volumes of documents.

What would seem to matter (if anything does) is duplication of work. Emacs manuals have seen attempts at French translations (that I’m aware of) for at least 20 years and none has reached completion (even if some seemed to have come pretty close).

I’ve tried to “align” all the old translations to produce en/fr chunks that could be easily used. It was not trivial because finding which version of Emacs they were based on was not easy and because I could not find the original texinfo files.

The current state of the repo is that there are already a number of chapters that have been completed, or that only miss a few paragraphs.


> That is the same reason for which I translated to French the Unofficial LaTeX manual, that allowed plenty of minor improvements on the manual (both English & French versions).

Thank you :)

Unlike LateX2e, the Emacs manuals evolve a lot. Over the course of 3 years, I’ve counted about 180,000 additional words, excluding modifications of the original sources including typos or factual errors.

Any translation process that handles such frequent changes must have a way to easily identify the location in the translation where the modification must take place.

And that’s exactly where “computer aided translation” tools come into play. The way they use bilingual chunks as the object the translator handles makes it trivial to identify where new translations are needed.

Jean-Christophe


-- 
Jean-Christophe Helary @jchelary@emacs.ch
https://traductaire-libre.org
https://mac4translators.blogspot.com
https://sr.ht/~brandelune/omegat-as-a-book/

Re: Where to contribute manual translations ? (Re: Emacs-devel Digest, Vol 238, Issue 29)

[Richard Stallman]

[[[ To any NSA and FBI agents reading my email: please consider    ]]]
[[[ whether defending the US Constitution against all enemies,     ]]]
[[[ foreign or domestic, requires you to follow Snowden's example. ]]]

Is this thread about translations of _the manuals included in the
Emacs distribution_?  Or is it about how Info can access translations
or manuals in general (including those not distributed with Emacs)?

Or something else?

-- 
Dr Richard Stallman (https://stallman.org)
Chief GNUisance of the GNU Project (https://gnu.org)
Founder, Free Software Foundation (https://fsf.org)
Internet Hall-of-Famer (https://internethalloffame.org)

Re: Where to contribute manual translations ? (Re: Emacs-devel Digest, Vol 238, Issue 29)

[Jean-Christophe Helary]

> On Dec 31, 2023, at 12:15, Richard Stallman <rms@gnu.org> wrote:
> 
> [[[ To any NSA and FBI agents reading my email: please consider    ]]]
> [[[ whether defending the US Constitution against all enemies,     ]]]
> [[[ foreign or domestic, requires you to follow Snowden's example. ]]]
> 
> Is this thread about translations of _the manuals included in the
> Emacs distribution_?  Or is it about how Info can access translations
> or manuals in general (including those not distributed with Emacs)?
> 
> Or something else?

The thread started as a question regarding where to contribute Emacs 
manuals French translation.

The digest to which I responded branched out as a summary of the 
previous discussions regarding Emacs manuals translation/localization 
and as a description of the current state of the French translation 
effort.

The non-digest thread involving Eli and Stefan discusses the possible 
locations of the translation sources, etc.

I am not aware that the discussion dealt with the way Info was 
accessing translation.


-- 
Jean-Christophe Helary @jchelary@emacs.ch
https://traductaire-libre.org
https://mac4translators.blogspot.com
https://sr.ht/~brandelune/omegat-as-a-book/

Re: Where to contribute manual translations ? (Re: Emacs-devel Digest, Vol 238, Issue 29)

[Eli Zaretskii]

> From: Richard Stallman <rms@gnu.org>
> Cc: emacs-devel@gnu.org
> Date: Sat, 30 Dec 2023 22:15:40 -0500
> 
> Is this thread about translations of _the manuals included in the
> Emacs distribution_?  Or is it about how Info can access translations
> or manuals in general (including those not distributed with Emacs)?

It is about the former, but it involves the latter as well, since the
Emacs manuals are installed in the system-wide info directory.  More
generally, the algorithms in info.el that search the pertinent
directories for a manual are designed to follow the conventions of the
Texinfo project that are followed by all GNU projects.  So adding
translated manuals must fit into those algorithms.

Re: Where to contribute manual translations ? (Re: Emacs-devel Digest, Vol 238, Issue 29)

[Richard Stallman]

[[[ To any NSA and FBI agents reading my email: please consider    ]]]
[[[ whether defending the US Constitution against all enemies,     ]]]
[[[ foreign or domestic, requires you to follow Snowden's example. ]]]


  > The digest to which I responded branched out as a summary of the 
  > previous discussions regarding Emacs manuals translation/localization 
  > and as a description of the current state of the French translation 
  > effort.

  > The non-digest thread involving Eli and Stefan discusses the possible 
  > locations of the translation sources, etc.

It sounds like this is thread is limited to how to include, in Emacs,
translation of the manuals in Emacs.  Is that right?

If so, ok.  I thought it might be broader than that.

-- 
Dr Richard Stallman (https://stallman.org)
Chief GNUisance of the GNU Project (https://gnu.org)
Founder, Free Software Foundation (https://fsf.org)
Internet Hall-of-Famer (https://internethalloffame.org)

Re: Where to contribute manual translations ? (Re: Emacs-devel Digest, Vol 238, Issue 29)

[Stefan Kangas]

Richard Stallman <rms@gnu.org> writes:

> It sounds like this is thread is limited to how to include, in Emacs,
> translation of the manuals in Emacs.  Is that right?

Yes, that's right.

Re: Where to contribute manual translations ? (Re: Emacs-devel Digest, Vol 238, Issue 29)

[Eli Zaretskii]

> From: Richard Stallman <rms@gnu.org>
> Cc: emacs-devel@gnu.org
> Date: Mon, 01 Jan 2024 22:20:19 -0500
> 
>   > The digest to which I responded branched out as a summary of the 
>   > previous discussions regarding Emacs manuals translation/localization 
>   > and as a description of the current state of the French translation 
>   > effort.
> 
>   > The non-digest thread involving Eli and Stefan discusses the possible 
>   > locations of the translation sources, etc.
> 
> It sounds like this is thread is limited to how to include, in Emacs,
> translation of the manuals in Emacs.  Is that right?

Basically, yes.  We only touch broader issues where that is necessary,
and try to find Emacs solutions that don't change those broader
aspects, like how Texinfo and Info work in general.