Sugestion to improve documentation translation (with deepl).

jlucas · 2022-02-12 22:31:49

Hello,

It might not be new for some of you, but I recently got to know an automatic translation machine that seems to be significantly better than what is being used in code_aster.

 https://www.deepl.com/translator

Lets see how it goes to translate U4.44.11 (just posting the results from a part of 3. Principles):

======== DeepL =====
3. Principles

This command is used to describe areas subject to one-sided contact conditions with or
without friction. The description is done at two levels:

- The global parameters such as the choice of the formulation or the control parameters of the
control parameters of the nonlinear solving algorithm (fixed point or Newton loops, specific parameters for the
for the solver) ;

- Local parameters specific to each contact zone.

The concept resulting from DEFI_CONTACT is then entered as a parameter in the simple keyword
CONTACT of the operators STAT_NON_LINE [U4.51.03] and DYNA_NON_LINE [U4.53.01]. Each zone
consists of two surfaces that can come into contact with each other and are described by the data of the groups of
which constitute them. For parallelism, it is advisable to use the centralized partitioning method
if the discrete formulation is used and/or if DYNA_NON_LINE is used (because of the
time patterns).

=== Code Aster current documentation (v14)====

3. Principles

This order makes it possible to describe the zones subjected to conditions of unilateral contact with or
without friction. Description is done on two levels:

- Total parameters like the choice of the formulation or the parameters of control of the non-linear
algorithm of resolution (loops of fixed point or Newton, parameters specific for the solvor);

- Local parameters specific to each zone of contact.

The concept resulting from DEFI_CONTACT is then well informed like parameter in the simple keyword
CONTACT operators STAT_NON_LINE [U4.51.03] and DYNA_NON_LINE [U4.53.01]. Each zone
understands two surfaces being able to make contact which are described by the data of the groups of
meshs which constitute them. For parallelism, one advises to use the method of centralized partitioning
if the discrete formulation is used and/or that one uses DYNA_NON_LINE (because of diagrams in
time).

=====

Something I really find funny/"irritating" is that the automatic translation takes all the text into account, including the parameters of the functions. I've found some things really to laugh at, like the "DEFECT" parameters, and the NAKED parameter to be found all around U4.43.01 (DEFI_MATERIAU) documentation.

I don't know how the automatized translation process works and I really think its awful to just criticise, so sorry for this one. But:

1. I don't understand why the documentation is not translated directly from the original (latex?) documents, with an exclusion clause to skip the parameters and parameter definition.

2. I don't understand why the translation process is not organised in a way to take some input from the user community. I guess its quite difficult to keep up to date with latest code development documentation, including new features and updates... but why not to elaborate a mixed methodology to take a solid base translation of at least some of the documents and get the automised translation for the rest? An open git account or wiki could help to put such concept into place?

To use well a software package is relatively important to have a clear and efficient documentation base. Specially if you are new (as is my case) to the subject.

Again the book from Jean-Pierre Aubry is really good to get you started (not sure if is enough though).

 https://framabook.org/beginning-with-code_aster

(a tip to new users: the latex version is available to download, which might help to copy paste the examples in order to get less syntax errors when running the command file examples...)

AsterO'dactyle · 2022-02-13 10:06:17

Hello

1/ Original docuemnts are in LibreOffice format (odt). The translation should take into account the exclusion of keywords, unfortunately this feature never worked well.
We are using a commercial product that we have paid for, but the technical support is not up to par.

2/ The documentation of aster includes nearly 25000 pages, updated every day, for two simultaneous versions.
In addition, there is a QA process to validate modifications (reviews of documents). I remind you that this software is used in the nuclear industry, with its constraints and requirements

The very frequently asked question is also: why is the documentation in French?
This is for two reasons:
1/ The qualification requirements for the nuclear industry, the users of the code are French, there should be no risk of misunderstanding because of the documentation.
2/ The developers of code_aster do not all speak English, in any case, not at a sufficient level for the documentation to be of quality.

It's been 20 years since we wanted to involve the community for translation. Many attempts have been made and failed.
1/ The QA process is too cumbersome to rely solely on people of goodwill
2/ The volume of documentation is considerable
3/ The update computer system for documentation management is not intended for
4/ The odt format of the documentation does not lend itself to this (knowing that we had the worst difficulties in the world to switch from the historical Word format to LibreOffice)

The documentation is certainly both the weakness and the strength of the software.
Weakness because it requires considerable human, financial and material resources that obviously nobody wants to pay.
Strength because it combines 30 years of experience and knowledge of modeling.

Consider that we have not even succeeded in obtaining theoretical documentation in LATEX, which is very expensive for researchers who have to duplicate their work on the documentation

We still hope to be able to make a major leap in the documentation concerning at least the documentations of the tests and the commands.

The idea would be to change the format to something that would be manageable with the source code (rst, Sphinx), which would greatly facilitate both the update process and the translation by the community.
In addition, a large part of the information contained in these documents could be generated automatically from the source, which would reduce the sources of errosr.

Unfortunately, for the moment, this idea is not accessible, the developers wanting to do it would like to be able to sleep sometimes at night
We have serious hopes of change since the code_aster industrial community has grown.

traemand · 2022-11-21 20:43:08

Hello,

What is the status of the french/english translation?

I'm interested in the:
- code_aster solver translation of error messages/warnings etc.
- salome_meca GUI translation (the very few AsterStudy translations have been a great addition! Why not translate more?)
- the documentation.

Going through the documentation is... frustrating. Is there any way to bring in the community to help translate the English part at least ? I realise the size of the task, but waiting for good, automatic translation of it could be many years.

Thank you for great, free software

Last edited by traemand (2022-11-21 20:44:04)

AsterO'dactyle · 2022-11-22 22:50:11

Hello,

Same answers ...
BUt ...
We are starting to transfer our historical documentation (odt => pdf format) to a new, more modern format (markdown/rst in sphinx).
Which should make things easier for the open source community.
For people who follow the latest versions, they must have seen the documentation of the new Python methods in the source.

jacob · 2023-03-18 13:31:30

Hello, I recommend using deepl, it is really better,
for example

MOMENT = (‘DRX’, ‘DRY MARTINI’, ‘DRZ’) MOMENT = (‘DRX’, ‘DRY’, ‘DRZ’)

MOYE_NOEUD= / ‘YES’, [DEFECT] MOYE_NOEUD= / ‘YES’, [DEFAULT]

if you download their translator, with just crtl+F8 you select the solver message and it is translated to english in a second

#1 2022-02-12 22:31:49

Sugestion to improve documentation translation (with deepl).

#2 2022-02-13 10:06:17

Re: Sugestion to improve documentation translation (with deepl).

#3 2022-11-21 20:43:08

Re: Sugestion to improve documentation translation (with deepl).

#4 2022-11-22 22:50:11

Re: Sugestion to improve documentation translation (with deepl).

#5 2023-03-18 13:31:30

Re: Sugestion to improve documentation translation (with deepl).

Board footer