Hello,
On 08.11.21 20:40, Sebastian Kuzminsky wrote:
Hello LinuxCNC people, there's a possible change brewing that I'd like
to ask for your feedback on.
The translations of our documentation into non-English languages has
been handled in an unusual and cumbersome way, and a new developer has
suggested a plan to modernize and streamline things.
I thought I should chime in, to help keeping the momentum - and the
other DD, Petter, was the one who came up with this, not me :)
I see two basic challenges:
a) localize the documentation to lower entry barriers for decision makers
b) localize the runtime GUIs to lower the barriers for users (which also
will affect a) ).
From what I see on YouTube, the individuals behind a) and b) are
typically the same person. But this hopefully changes with automation
soon found everywhere.
The .po files are known to help with the runtime localisation for ages.
Every language has a file with pairs of lines - English first, localized
underneath. These lists are extracted and mainted automatically with the
source code. This po4a I did not know about before. They now extends
that principle with documentation. So, when the English manual has
paragraphs reordered, the other languages are equally reordered. No
exact idea yet how this works with single sentences introduced or words
changed but am confident these folks found something reasonable.
There is a c). Show to the world that LinuxCNC keeps rejuvenating itself.
How things are now:
* All our documentation is maintained in Asciidoc format in the git
repo, and built into HTML and PDF by the build system.
* The "main" documentation is maintained in English.
* To create a new translation, a translator copies the asciidoc source
of the English documentation to a new language-specific asciidoc
source file. For example: `README.adoc` -> `README_fr.adoc`. They
edit the new file and translate the words.
That's it! Simple, but it has a couple of problems...
Problems with the current system:
* If the English-speaking developers change the main documentation
file there is no automatic process to notify the translators, and the
translated docs slowly drift out of date with the main English docs,
without us really knowing.
Right. This will not be automagically solved, people still need to
translate, but it will manageable since you see what paragraphs have
been changed and also see the corresponding outdated chunk of
translation next to it.
* The translations of the docs are handled differently than the
translations of the software. The translations of the strings in the
software is done using a widely used system called "gettext", which
has a suite of tools to identify translatable strings in programs and
maintain a database of what those strings should look like in
different languages. You can learn more about gettext here:
<https://www.gnu.org/software/gettext/manual/gettext.html#Why>
Gettext and .po files are a long established technology. There are also
many auxiliary tools to help with the translation. That should be mostly
painless. The danger is that someone light-heartedly translates units
without thinking straight, like "inch" to "mm". I have no doubt that
this will be caught quickly, though.
The new proposal is basically to use gettext for everything, both the
software and the documentation. This would be done using a system
called po4a: <https://po4a.org/>
Moving the docs translations to po4a would let us use the standard
gettext tools, including online tools like Weblate, to maintain the
translations. gettext keeps track of what "main" english strings have
changed, and flags the translations of those strings as "out of date",
so that translators know they need attention. Out-of-date translations
automatically fall back to using the up-to-date english strings.
I'm not very experienced with translations, so I'm asking for comments
from the folks who currently do the work of translating LinuxCNC (both
docs & software) into non-English languages...
Debian has translations of its package descriptions. And even though all
my professional life is in English, when I read through
https://blends.debian.org/med/tasks/bio (please have a look) you will
find that there is an extra edge to those descriptions that are
translated. I find that amazing and this experience helped me to keep my
arrogance in check.
Do you have any concerns, input, or comments on this proposal?
I think it is one the most important developmental steps for LinuxCNC to
take. The translations should preferably not be performed by the
developers but by the users.
Would you be willing to verify and update the translations into your
languages?
Wrong addressees. Let me try rephrase that: "Would you be willing to
help organizing translations into your languages and to help your local
user base to contribute and forward their problems?" Problems likely are
differences in the order words in sentences that would affect the C code
and just all the other known and unknown unknowns out there.
In principle I could help. But you should not trust me, yet, as I still
need a lathe or mill. And you should find someone who knows for longer
than only a few weeks that backlash (hey, you have compound words in
English, too) is "Umkehrspiel" in German (which, albeit not found by
google translate, is a much nicer word - umkehr is the reversal, spiel
(game) is the movement/activity without purpose or function).
What can we software people do to help make this task easier?
Webinars. Meetings. And you already mentioned these web interfaces.
Best,
Steffen
_______________________________________________
Emc-developers mailing list
Emc-developers@lists.sourceforge.net
https://lists.sourceforge.net/lists/listinfo/emc-developers
