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/