CIP-1694 | Adding French translation

[Hornan7]

Each line has been meticulously translated into French and we are committed to keeping it updated according to each new commit of the original document.

---

(rendered version in branch)

[rphair]

@Hornan7 the document content looks great in readability and formatting: thanks to yourself and whoever you are working with to achieve this, with ongoing thanks for offering to keep it updated.

To my knowledge we've not had a parallel language version of a CIP before, so here are my suggestions which @KtorZ @Ryun1 might confirm or debate:

1 - The CIP header data at the beginning of the document, for all translations other than the primary (English) language, should be human- rather than machine-readable. We are still catching up on our tooling to build generated web sites (cips.cardano.org and developers.cardano.org/docs/governance/cardano-improvement-proposals) which can only happen after we finish standardising header data in a single language (#389)... perhaps someday we will have language independence in the CIP database but we're far from ready to support that.

Therefore any usage of the machine-readable format in the header for multiple languages is going to be ignored, and it doesn't format properly on GitHub for the human reader: so I would recommend these fields be put in Markdown prose (e.g. lists of authors and discussion links) at the beginning of the document: for your convenience and that of your readers.

2 - Your impressive commitment to "keeping it updated" needs to be documented somehow, both before this PR is merged and into the future:

2a) at least: the translator name(s), human readable date, and GitHub hash of the English/primary CIP-1694 document which you have translated in your non-English version, or:

2b) preferably, in my opinion: a "version history" table which has this information added as a new line of a table or list each time a new translation is submitted as a PR.

At it stands now, there is no notion of "we" other than you, and no notion of "original document" except presumably the latest commit in CIP-1694 listed here (https://github.com/cardano-foundation/CIPs/commits/master/CIP-1694/README.md)... currently only one commit, but that is about to change radically in light of #380 (comment).

But your brilliant work is just a couple steps away of achieving multi-lingual auditability for this document and I assure you I/we will do everything we can to assist you in that effort. 🤓

[Hornan7]

Thank for those nice comments, Its mainly me and Lafleur who worked on this but he doesn't know much about github.

As for the commit history of this document, I'll have to blame my lack of knowledge. I had to copy a new version of the document (without its commits to then perform the PR).
the commit history is in my repository:
(https://github.com/Hornan7/CIP-1694-FR/commits/main)

Our primary objective, for me and Lafleur, was to reproduce the original document exactly line by line in French in the same form. That being said, our motivation remains unchanged and we will do our best to rework it for you in the form that will please everyone. We will both keep track of the commits and I will make the changes accordingly. 😃👍

[rphair]

the commit history is in my repository:
(https://github.com/Hornan7/CIP-1694-FR/commits/main)

good to know the source; although unless other editors disagree with point # 2 in #539 (review), the way forward for this PR is to link to the latest commit on the English document, not the French one.

[KtorZ]

@rphair: The CIP header data at the beginning of the document, for all translations other than the primary (English) language, should be human- rather than machine-readable.

I (rather strongly) disagree here. The YAML preamble is a structured format, meant to be machine-readable. The keys in the mapping are well-defined and shall remain in English. In the same way that by convention in western countries, any comments in source code is written in plain English.

@rphair: Therefore any usage of the machine-readable format in the header for multiple languages is going to be ignored

That is another option that I would be quite in favor of. We could omit the preamble altogether on translation, or perhaps, have an alternative preamble for translated content (which I think addresses your other points @rphair) For example:

---
cip: 1694
locale: fr-FR
translators:
  - Hornan <[email protected]>
  - Lafleur <[email protected]>
revision: abcdef12
---

---

As for the PR itself, I'll give a read to the French translation this week and provide some feedback.

[rphair]

have an alternative preamble for translated content

yes @KtorZ I like the way the alternative "localisation" preamble looks & could work in practice.

Question overall: could it be useful to the human and/or the machine reader to have an translated full CIP preamble with English keys and French values? At this time the only list of authors and discussion links is in the preamble, so if we omitted the full CIP header we'd be omitting this vital context for French readers... which was why I'd suggested putting these lists in the markup.

The revision history on the French document itself (just one English commit ID for each version) would preclude the need to have a human readable "version history" table, since links to previous translations would then be in the French document commit history. So it would be more concise to have this ID only once in each document: in the header as potentially more useful machine-readable data.

So I believe the question is whether to merge the translated full CIP preamble fields in with the extra localisation preamble fields above (or maybe have 2 preambles?)... or to use that new translation preamble instead and include the Authors: and Discussions: some other way.

[Hornan7]

@KtorZ The keys in the mapping are well-defined and shall remain in English. In the same way that by convention in western countries, any comments in source code is written in plain English.

We had actually talked about it myself and Lafleur and came to the conclusion that it was preferable at the time of the translation to keep them in English so that at the technical level, future French Dreps / Spo / CC could recognize the exact name of these parameters on which they will have to vote and/or debate.

@KtorZ We could omit the preamble altogether on translation, or perhaps, have an alternative preamble for translated content (which I think addresses your other points @rphair) For example:

---
cip: 1694
locale: fr-FR
translators:
  - Hornan <[email protected]>
  - Lafleur <[email protected]>
revision: abcdef12
---

I quite like this example. I will make whatever changes are best for you and modify the document accordingly. 😃👍

@rphair The revision history on the French document itself (just one English commit ID for each version) would preclude the need to have a human readable "version history" table, since links to previous translations would then be in the French document commit history. So it would be more concise to have this ID only once in each document: in the header as potentially more useful machine-readable data.

if each commit in French is done this way, (With a link referring to the commit in English for each commit), this would effectively allow me to considerably reduce the "visual weight" of the history in the document and also allow you to keep track of these references in the github commit history. 😇

[KtorZ]

@rphair: could it be useful to the human and/or the machine reader to have an translated full CIP preamble with English keys and French values?

It could be, especially if we start rendering internationalized versions of CIPs on the website. At present though, this would be unnecessary. Especially because beyond the title, there isn't much translation to do. So what about we settle on a "translation header preamble" (can amend CIP-0001 consequently) as well as a naming convention for files / folder. We also have the case with CIP-0050 which I dug back some days ago that has a Spanish translation.

So, the proposal would be as follows:

• Any translated file (README.md or anything else, even images) shall be renamed with a new suffix on the file basename using ISO 639-1 language code, separated by a dot . character. So for example: README.fr.md. When no language code is provided, the default language for the document is assumed to be English (UK/US).

• Translated CIPs, must not include the original preamble. But they must instead include the following preamble as yaml frontmatter data:

Field	Description
CIP	The CIP number (without leading 0) being translated
Title	A translation of the CIP's title
Revision	The commit hash (8-10 first hex-digits) of the source (e.g. 12ab34cd)
Translators	A list of translators names and email addresses (e.g. John Doe <[email protected]>)
Language	An ISO 639-1 code of the target language (e.g. fr)

(The language in the preamble might be redundant with the filename extension though...)

@Hornan7: We had actually talked about it myself and Lafleur and came to the conclusion that it was preferable at the time of the translation to keep them in English so that at the technical level, future French Dreps / Spo / CC could recognize the exact name of these parameters on which they will have to vote and/or debate.

Yes, I think it's best to keep parameters and "well-known" names in English, though it's not excluded to give a translation for the sake of understanding. Fortunately, maths-inclined folks tend to often just use single letters from the greek alphabet so translation isn't even needed.

[rphair]

Translated CIPs, must not include the original preamble.

Sounds good according to the above general guideline. But as the devil's advocate, what is the user experience of the French reader in this case who is directed to the GitHub pathname for README.fr.md and

• wants to follow the Discussion links? They click on... what?
• wants to view the Authors?
• Could they have a URL to click back & look on the original English/primary document header for either of these things?

It can be argued that GitHub makes these things available (to readers with some GitHub experience) by going over to the primary file README.md but then it appears we are forcing non-English readers to read the English document. This could make sense for technical / document management but not from a UX point of view.

[KtorZ]

@rphair I invite you to continue the conversation on i18n here: #542. Let's keep this PR about the French translation of CIP-1694 and move the conversation about how to support i18n as part of the process.

(Note: I have acknowledged your last statement, and suggest a change compared to my comment just above).

[Hornan7]

Let me know if the changes are suitable. I can modify it if necessary if you want me to add additional information such as a list of commit hash of my old updates or some links to discussions in french on cardano forum or twitter for example.

[rphair]

@Hornan7 we (w/ @KtorZ) added a new field as per #542 while the i18n requirements are still being reviewed...

[rphair]

... p.s. resubmitting this 1 item because change was anchored in the wrong place:

[Hornan7]

@rphair maybe i misunderstood, I tought i had to take off "CIP: 1694" and replace it by source.

[rphair]

@KtorZ can you think of any advantage to allowing an arbitrary length commit hash here, rather than the 7-digit hashes displayed on the commit history page? https://github.com/cardano-foundation/CIPs/commits/master/CIP-1694/README.md

The problem I can foresee is that searching the commit history page for the 8+digit commit hash won't return a match; while the 7-digit hash will. 😟

[rphair]

@Hornan7: ... maybe i misunderstood, I tought i had to take off "CIP: 1694" and replace it by source.

no, we're just following what's already been written for #539 (comment) and updating with the fields listed in #542... Therefore it's assumed that the Translations header begins with the CIP field.

@KtorZ based on this uncertainty, it may be a problem that the translation preamble doesn't include the CIP field as it does in https://github.com/cardano-foundation/CIPs/blob/master/CIP-0001/README.md#header-preamble ... I'm going to suggest a change in #542 that we add that line into the table to avoid further problems like this (as you say, we can continue the general discussion there).

[Hornan7]

I'm going to suggest a change in #542 that we add that line into the table to avoid further problems like this (as you say, we can continue the general discussion there).

Yes please, I'm getting confused here as i'm trying to make the changes according to the structure in #542 . hahaha.
It would be nice, not having to search left and right. :)
;)

[rphair]

Current translation header requirement is well satisfied: https://github.com/cardano-foundation/CIPs/blob/master/CIP-0001/README.md#translations

and the translation of all literals back to English (in the document as well as the header) is one of the last of the tricky requirements: also looking good.

I had a feeling the section anchors would also be tricky so I double checked them all (they might need to be triple checked)...

(There is one I pointed out in #547 but @Hornan7 that should not be fixed in this PR since that's a problem with the source document that will be fixed in a future commit... not the one that's being translated here... unless also updating the commit hash after that PR is merged.)

(The footnote links to the Shelley and Alonzo ledger specs are also dead here & in the original document (fixed in #548) but likewise those bad links should be kept here unless merged there first & updating the commit hash here.)

[rphair]

@KtorZ @Ryun1 @SebastienGllmt I would hope this can be confirmed & merged as a baseline before we start doing too much work through the other CIP-1694 PRs that have been opened in the last week.

[Hornan7]

We also noticed these bad links but did not mention them in comments in the original document. (we should have, sorry). That being said, me and lafleur are closely watching #543 #545 #547 and #548 pull requests in review. We will modify the translation when they are merged.

[rphair]

Thanks @Hornan7 then we'll go ahead and merge this now since 1) it's a currently accurate reflection of the English document that's been 8 or 9 months in the making... and most importantly because 2) for the next few months there's not going to be any time when there isn't at least one pending PR on CIP-1694, so this moment of congruence is not likely to come again soon.

The editors will therefore leave it to you about how often & in response to what kinds of updates you submit the next PR on the translated document; and thanks for keeping an eye on the PR threads like the ones you quote above. 🤓