An attempt to improve the repository

[lrusso96]

Hi, first of all thanks for the material. Here are some suggestions about the general structure of the project and how you could better achieve the goals described in your README file.

Open-Source and Locales

• GitHub allows developers to modify the code, report and fix errors. I think it is the best way to keep the project active, maintain this repo and add new translations.
• I have setup a simple repository which you could look at: what I do, is to use ConTeXt modes to achieve multi language support. I think that currently this repository lacks in modularity, since each language has a dedicated folder and even common files (e.g. the enviroment) are basically a copy and paste. Imagine you want to update the cover (not the text, that depends on the language, but just the layout); now, you should modify 3 different files because there are 3 languages; what generally happens is that some file is not updated, or there is some error in copy and paste, etc. What I suggest you is then to use a modular approach.
• If you look at my repo, you will see that in a single command you can compile all the documents at-once. This is ideal when working with tools like GitHub, because you let GitHub to "continuously" compile the documents, at each commit: generally, these documents are produced and modified on a different branch, e.g. "beta", and once you are satisfied with them you merge with the master branch and upload a new release as an asset.
• Final suggestion: you should add a License to your repository, there is a dropdown menu on GitHub for that. This is strongly suggested when publishing the source-code and working with Open-Source projects.

Italian Version

Also, I would be interested in starting an Italian translation of your document.

Final considerations

Let me know what you think about that. Feel free to convert this issue into a discussion thread (again, this is possible on GitHub) so that other people can easily communicate and interact.

Cheers!

[garulfogb]

Hi, great ideas, I took note of them today (very late) and will try to convert the current structure to your proposed one.

[ghost]

@lrusso96: The main issue remains the translations but, in retrospect, GitHub only served as a code hosting platform. Nevertheless, as a result, what you propose is interesting.

I propose that we work on the exchanges. Unfortunately, it supposes that we can use the right translation tools.

<xliff xmlns="urn:oasis:names:tc:xliff:document:2.0"
       xmlns:ctr="urn:oasis:names:tc:xliff:changetracking:2.0"
       version="2.1"
       srcLang="en" trgLang="fr">
  <file id="f1">
    <unit id="u1">
      <ctr:changeTrack>
    <ctr:revisions appliesTo="segment" currentVersion="r1">
      <ctr:revision author="Frank" datetime="2021-27-01T11:00:00+2:00"
            version="r1">
            <ctr:item property="state">reviewed</ctr:item>
      </ctr:revision>
      <ctr:revision author="Bob" datetime="2021-07-01T15:00:00+2:00"
            version="r2">
        <ctr:item property="state">translated</ctr:item>
      </ctr:revision>
    </ctr:revisions>
    <ctr:revisions appliesTo="target" currentVersion="r1">
      <ctr:revision author="Bob" datetime="2021-07-01T15:00:00+2:00"
            version="r1">
        <ctr:item property="content">Bonjour</ctr:item>
      </ctr:revision>
    </ctr:revisions>
    <ctr:revisions appliesTo="note" ref="n1" currentVersion="r1">
      <ctr:revision author="Bob" datetime="2021-07-01T15:02:00+2:00"
            version="r1">
        <ctr:item property="content">Please Review my translation</ctr:item>
      </ctr:revision>
    </ctr:revisions>
      </ctr:changeTrack>
      <notes>
    <note category="comment" id="n1">Please Review my translation</note>
      </notes>
      <segment state="reviewed">
    <source>Hello</source>
    <target>Bonjour</target>
      </segment>
    </unit>
  </file>
</xliff>

XLIFF is an exchange format (spec.: XLIFF v2.1) that can fullfills some expectations. Nevertheless, the latest version is not always supported by translation tools. Although it can help someone to translate a document it is not a magic solution: you need to have translation skills because translating a document can be hard.