Translation of the Org mode manual (was: Translation of manuals (was: SES manual French translation))

Translation of the Org mode manual (was: Translation of manuals (was: SES manual French translation))

[Ihor Radchenko]

Jean-Christophe Helary <jean.christophe.helary@traductaire-libre.org>
writes:
> I’m not sure this is the place to discuss translation theory...

Let me steer this discussion to non-texi manuals - Org mode manual.
We also had a few requests about translations, although Org mode needs
are more general compared to a very focused task of translating texi
manuals:

1. Org mode manual itself, just like the other Emacs manuals may need to
   be translated. However, Org mode manual source is written in Org mode
   format, not texi. It is just transformed to texi as one of the export
   options.

2. Org mode website has several translations (French, Japanese, and
   Mandarin). The website sources are written in Org mode, but the work
   of translation was done be enthusiasts, and we have no good system to
   maintain the main English version of the website in sync with the
   translations.

3. A number of Org mode users are using Org sources to publish
   multi-lingual books. Such publishing is a bit more challenging
   compared to translation as it requires special book layout.

Therefore, there is a demand to have a toolset for translating Org mode
documents.

So far, I have been thinking about some way to support translations with
ideas rather similar to raised in this topic:

1. Mark paragraphs/headings/other structural elements with an ID

2. Split translation into chunks linked to the original source IDs and
   their text hash

3. When exporting from Org source to target format (texi, html, pdf,
   etc), allow choosing the target language(s) and ensure consistency
   between translations and their possibly changed sources.

However, I did not know about po4a. It is possible that many of the
necessary design decisions are already in place in po4a.

> ...
> I think po-mode already does that and all the "out of emacs" tools do 
> too.

May you share the most important features of po-mode that you find
essential to your translation work?

>> @node Display Margins
>>  @subsection Displaying in the Margins
>>  @cindex display margins
>>  @cindex margins, display
>
> As long as the above strings are to be translated, they need an ID too.
>
>>  @c para 1234
>> 
>>  @c para 1235
>> 
>>  @c para 1236
>
> Is the numbering automatic?
>
> What if you add paragraphs in the middle, like Vincent did? Will the 
> author have to check the IDs and add a number that’s not used already?
>
> There are plenty of issues with static IDing parts of a document.

May you please elaborate on the issues with static IDs?

-- 
Ihor Radchenko // yantar92,
Org mode contributor,
Learn more about Org mode at <https://orgmode.org/>.
Support Org development at <https://liberapay.com/org-mode>,
or support my work at <https://liberapay.com/yantar92>

Re: Translation of the Org mode manual (was: Translation of manuals (was: SES manual French translation))

[Jean-Christophe Helary]

Ihor,

Thank you for chiming in.

> On Jan 4, 2024, at 20:34, Ihor Radchenko <yantar92@posteo.net> wrote:
> 
> Jean-Christophe Helary <jean.christophe.helary@traductaire-libre.org>
> writes:
>> I’m not sure this is the place to discuss translation theory...
> 
> Let me steer this discussion to non-texi manuals - Org mode manual.

Sure.

> We also had a few requests about translations, although Org mode needs
> are more general compared to a very focused task of translating texi
> manuals:
> 
> 1. Org mode manual itself, just like the other Emacs manuals may need to
>   be translated. However, Org mode manual source is written in Org mode
>   format, not texi. It is just transformed to texi as one of the export
>   options.

That’s correct and that texi file seems to choke po4a, which is the 
reason my script removes it and uses the .org original instead.

I use the txt filter in po4a to convert it to po:

https://git.sr.ht/~brandelune/emacs_documentation_repository/tree/main/item/emacs_docs2po.sh#L71

The result is here:

https://git.sr.ht/~brandelune/emacs_documentation_repository/tree/main/item/doc/misc/org.org.fr.po

And looks like this:

---
#. type: Plain text
#: /Users/suzume/Documents/Repositories/Projet OmegaT de Documentation Emacs -
#: Sources/doc/misc/org.org:24
msgid ""
"Org Mode is an authoring tool and a TODO lists manager for GNU Emacs.  It "
"relies on a lightweight plain-text markup language used in files with the "
"=.org= extension."
msgstr ""

#. type: Plain text
#: /Users/suzume/Documents/Repositories/Projet OmegaT de Documentation Emacs -
#: Sources/doc/misc/org.org:31
msgid ""
"As an authoring tool, Org helps you write structured documents and provides "
"exporting facilities. Org files can also be used for literate programming "
"and reproducible research.  As a TODO lists manager, Org helps you organize "
"your tasks in a flexible way, from daily needs to detailed project-planning, "
"allowing logging, multiple views on your tasks, exporting your agendas, etc."
msgstr ""

#. type: Plain text
#: /Users/suzume/Documents/Repositories/Projet OmegaT de Documentation Emacs -
#: Sources/doc/misc/org.org:38
msgid ""
"Org mode is implemented on top of Outline mode, which makes it possible to "
"keep the content of large files well structured.  Visibility cycling and "
"structure editing help to work with the tree.  Tables are easily created "
"with a built-in table editor.  Plain text URL-like links connect to "
"websites, emails, Usenet messages, BBDB entries, and any files related to "
"the projects."
msgstr ""
---

In OmegaT it looks like this (all the po decorations are hidden - 
protected - in the editor, only the translatable parts are displayed):

---
¶

Org Mode is an authoring tool and a TODO lists manager for GNU Emacs.

It relies on a lightweight plain-text markup language used in files 
with the =.org= extension.

¶

As an authoring tool, Org helps you write structured documents and 
provides exporting facilities.

Org files can also be used for literate programming and reproducible 
research.

As a TODO lists manager, Org helps you organize your tasks in a 
flexible way, from daily needs to detailed project-planning, allowing 
logging, multiple views on your tasks, exporting your agendas, etc.

¶

Org mode is implemented on top of Outline mode, which makes it possible 
to keep the content of large files well structured.

Le cycle de visualisation et la modification de la structure aident à 
travailler avec l'arborescence.

Les tableaux sont facilement créés avec un éditeur de tableau intégré.

Les liens de type URL en texte brut se connectent aux sites Web, aux 
e-mails, aux messages Usenet, aux entrées BBDB et à tous les fichiers liés 
aux projets.

¶
---

You’ll notice that a few sentences have been translated in the last 
paragraph.

In other tools that support the PO format, similarly the PO decorations 
would be hidden from view.

> 2. Org mode website has several translations (French, Japanese, and
>   Mandarin). The website sources are written in Org mode, but the work
>   of translation was done be enthusiasts, and we have no good system to
>   maintain the main English version of the website in sync with the
>   translations.

I think you should take a look at how Debian does that, even if their 
site sources are not in org. The process is the same. Debian has a huge 
amount of experience in documentation/web localization.

> 3. A number of Org mode users are using Org sources to publish
>   multi-lingual books. Such publishing is a bit more challenging
>   compared to translation as it requires special book layout.

Indeed.

> Therefore, there is a demand to have a toolset for translating Org mode
> documents.
> 
> So far, I have been thinking about some way to support translations with
> ideas rather similar to raised in this topic:
> 
> 1. Mark paragraphs/headings/other structural elements with an ID
> 
> 2. Split translation into chunks linked to the original source IDs and
>   their text hash
> 
> 3. When exporting from Org source to target format (texi, html, pdf,
>   etc), allow choosing the target language(s) and ensure consistency
>   between translations and their possibly changed sources.
> 
> However, I did not know about po4a. It is possible that many of the
> necessary design decisions are already in place in po4a.

po4a has been around for a while and is used in a lot of free 
documentation projects. A lot of tools that free software translators 
use fully support the PO format and the translation teams are used to 
the process of team translating/proofreading/validating/committing.

I am sure Martin Quinson would appreciate development of a dedicated 
org mode filter. Right now, as I wrote above, the plain text filter is 
sufficient.

Also, po4a is not only a filter, it is a tool equivalent to gettext but 
focused on documentation formats. You should check its documentation to 
see how your workflow could benefit from its design.

>> ...
>> I think po-mode already does that and all the "out of emacs" tools do
>> too.
> 
> May you share the most important features of po-mode that you find
> essential to your translation work?

I don’t use po-mode. po-mode is not sufficient (now) for most of the 
professional translation that I handle.

>>> @node Display Margins
>>> @subsection Displaying in the Margins
>>> @cindex display margins
>>> @cindex margins, display
>> 
>> As long as the above strings are to be translated, they need an ID too.
>> 
>>> @c para 1234
>>> 
>>> @c para 1235
>>> 
>>> @c para 1236
>> 
>> Is the numbering automatic?
>> 
>> What if you add paragraphs in the middle, like Vincent did? Will the
>> author have to check the IDs and add a number that’s not used already?
>> 
>> There are plenty of issues with static IDing parts of a document.
> 
> May you please elaborate on the issues with static IDs?

For one, the fact that the numbering ends up not being sequential after 
a while. If you have a tool that does all the grunt work, then any 
kind of ID system should work.

In PO, the message is the ID.



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

Re: Translation of the Org mode manual (was: Translation of manuals (was: SES manual French translation))

[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. ]]]

> 1. Org mode manual itself, just like the other Emacs manuals may need to
>   be translated. However, Org mode manual source is written in Org mode
>   format, not texi. It is just transformed to texi as one of the export
>   options.

Using Org format for the source of a document, and converting it to
texi for processing (for instance, through TeX) would be a fine method
to use, if it worked.  But it doesn't actually work.

The problem is that it cannot work, given Org format as it exists now.
It cannot properly represent manuals that use the GNU standard style
because it does not have ways to represent all the distinctions that
are needed.

Texinfo implements semantic markup, and is designed for multiple
output formats, including Info, HTML, and DVI (whence also PDF).  Two
different markup constructs that look the same in one output format
may look different in another.  All these design decisions were the
result of long thought.

For instance, italic face can be the result of @dfn, @var, @emph,
@cite and @i.  Each of them has a meaning -- which one to use is not a
matter of taste.

@cite is used around the title of a book.
@dfn is used around the first use of a term, to say it is being defined.
@emph is used to indicate emphasis.
@var is used around a metasyntactic variable.

@i means "use italic for this" and does not say why.  It is a escape
for situations that Texinfo has no specific way to describe.

These five commands produce the same output in DVI/PDF, but different
output in Info.

I think there must be 15 different Texinfo commands to generate
fixed-width bold text in DVI/PDF.

To represent a manual source in Org format and do the job right is not
possible with Org format as it is now.  To make it possible requires
extending Org format so it can make all the distinctions Texinfo can
make.

I would like Org format to be extended in this way.

Texinfo format is often misunderstood.  People write GNU manuals
without knowing of all these constructs, so they use the wrong
construct.  If Org format were extended to do _the whole job_, we
could convert all manuals to Org format once and for all.

A few years ago I raised this idea, but nobody wanted to work on it.

-- 
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: Translation of the Org mode manual (was: Translation of manuals (was: SES manual French translation))

[Ihor Radchenko]

Richard Stallman <rms@gnu.org> writes:

> Using Org format for the source of a document, and converting it to
> texi for processing (for instance, through TeX) would be a fine method
> to use, if it worked.  But it doesn't actually work.
>
> The problem is that it cannot work, given Org format as it exists now.
> It cannot properly represent manuals that use the GNU standard style
> because it does not have ways to represent all the distinctions that
> are needed.
> ...

This is not true. We can generate a precise TeXinfo markup from Org
files even now using export snippets: @@texinfo:<direct texinfo code>@@

So, Org mode manual in particular can be adapted if absolutely
necessary.

Another question is that having native Org mode constructs for
manual-specific markup would make things less verbose and ad-hoc. But
that question is out of scope of this particular discussion, which is
focused on translation tools.

> I would like Org format to be extended in this way.
>
> Texinfo format is often misunderstood.  People write GNU manuals
> without knowing of all these constructs, so they use the wrong
> construct.  If Org format were extended to do _the whole job_, we
> could convert all manuals to Org format once and for all.
>
> A few years ago I raised this idea, but nobody wanted to work on it.

Your idea is not forgotten. But the resources for Org mode development
are limited. In particular, I am currently not prioritizing adding
brand-new features in favour of helping contributors, improving the
existing functionality, and fixing the existing problems.

If somebody is interested to work on adding new Org mode features like
custom inline markup, please contact Org mode mailing list. We can guide
the volunteers through the contribution process and help with any
questions when they arise.
See https://orgmode.org/worg/org-contribute.html

-- 
Ihor Radchenko // yantar92,
Org mode contributor,
Learn more about Org mode at <https://orgmode.org/>.
Support Org development at <https://liberapay.com/org-mode>,
or support my work at <https://liberapay.com/yantar92>

Re: Translation of the Org mode manual (was: Translation of manuals (was: SES manual French translation))

[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. ]]]

  > This is not true. We can generate a precise TeXinfo markup from Org
  > files even now using export snippets: @@texinfo:<direct texinfo code>@@

I know that it is possible to convert Org format to Texinfo.  I am
raising a different issue.  I think we are miscommunicating.

The question is not whether Org can be translated to Texingo.  The
question is whether Org format can represent all the distinctions that
Texinfo represents.  Or, equivalently, is it possible to translate
Texinfo text to Org format and then back to Texinfo format without
losing any information?

Last I looked, that was not possible, because of the issue I
explained in my previous message.

If things have improved and Org format is now capable of doing this, I
will consider that good news.

  > Another question is that having native Org mode constructs for
  > manual-specific markup would make things less verbose and ad-hoc.

To handle GNU manuals using Org format would not require a feature
like 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)