programminghistorian / ph-submissions

The repository and website hosting the peer review process for new Programming Historian lessons
http://programminghistorian.github.io/ph-submissions
136 stars 111 forks source link

Calibrating Radiocarbon Dates with R (translation from french) #603

Open hawc2 opened 5 months ago

hawc2 commented 5 months ago

Programming Historian in English has received a proposal for a translation from French: 'Calibrating carbon ages in R' by @torontoyyz

I have circulated this proposal for feedback within the English team. We have considered this proposal for:

**We are pleased to have invited @torontoyyz to develop this Proposal into a Submission under the guidance of @lachapot and @digitalkosovski.

The Submission package should include:

We ask @torontoyyz to share their Submission package with our Publishing team by email, copying in the editors.

We've agreed a submission date of early April. We ask @torontoyyz to contact us if they need to revise this deadline.

When the Submission package is received, our Publishing team will process the new lesson materials, and prepare a Preview of the initial draft. They will post a comment in this Issue to provide the locations of all key files, as well as a link to the Preview where contributors can read the lesson as the draft progresses.

If we have not received the Submission package by April, @lachapot will attempt to contact @torontoyyz. If we do not receive any update, this Issue will be closed.

Our dedicated Ombudspersons are Ian Milligan (English), Silvia Gutiérrez De la Torre (español), Hélène Huet (français), and Luis Ferla (português) Please feel free to contact them at any time if you have concerns that you would like addressed by an impartial observer. Contacting the ombudspersons will have no impact on the outcome of any peer review.

TorontoYYZ commented 3 months ago

Hooray! Here's the initial translation in plain R - it's not in Markdown yet, but that's coming. Figures and table images are also in this zip.

Thanks for being patient and supportive! initial-translation-without-markdown.zip

anisa-hawes commented 3 months ago

Hello Christina @TorontoYYZ,

Many thanks for sharing your submission materials with us. @charlottejmc and I are happy to set up the file as Markdown for you, so we'll take it from here!

When we've processed your materials, we'll post a comment here in the Issue to the share locations of all the key files.

Very best wishes for now, Anisa

charlottejmc commented 3 months ago

Hello @digitalkosovski, @lachapot and @TorontoYYZ,

You can find the key files here:

You can review a preview of the lesson here:


I noticed a couple things while processing this submission, which I've outlined below:

Thank you very much for your patience and your work!

anisa-hawes commented 3 months ago

Hello Christina @TorontoYYZ,

What's happening now?

Your lesson has been moved to the next phase of our workflow which is Phase 2: Initial Edit.

In this Phase, your editors Laura @lachapot and Agustín @digitalkosovski will read your translation, and provide some initial feedback. They'll post feedback and suggestions as a comment in this Issue, so that you can revise your draft in the following Phase 3: Revision 1.

%%{init: { 'logLevel': 'debug', 'theme': 'dark', 'themeVariables': {
              'cScale0': '#444444', 'cScaleLabel0': '#ffffff',
              'cScale1': '#882b4f', 'cScaleLabel1': '#ffffff',
              'cScale2': '#444444', 'cScaleLabel2': '#ffffff'
       } } }%%
timeline
Section Phase 1 <br> Submission
Who worked on this? : Publishing Assistant (@charlottejmc) 
All  Phase 1 tasks completed? : Yes
Section Phase 2 <br> Initial Edit
Who's working on this? : Editors (@lachapot + @digitalkosovski)  
Expected completion date? : June 3
Section Phase 3 <br> Revision 1
Who's responsible? : Translator (@TorontoYYZ) 
Expected timeframe? : ~30 days after feedback is received

Note: The Mermaid diagram above may not render on GitHub mobile. Please check in via desktop when you have a moment.

anisa-hawes commented 3 months ago

Hello again @TorontoYYZ,

In the meantime, I've invited you to join us here on GitHub as an Outside Collaborator. This will give you the Write access you'll need to edit your lesson directly. Charlotte has shared some notes above about a few components that are still needed / details that we'd like to help clarify.

The French original lesson was published before we introduced alt-text for all figures, so I realise that you don't have the original alt-text available to translate. For writing the alt-text, this resource may be useful. It advises that the alt-text for graphs and data visualisations should consist of the following:

alt="Chart type of data type where reason for including chart"

You can either add the alt-text into the templates Charlotte created, or leave a comment here in the Issue and we will add it in for you.

Thank you, Anisa

lachapot commented 3 months ago

Hi everyone,

Thank you very much for your translation, @TorontoYYZ . And thank you @charlottejmc and @anisa-hawes for setting it all up! We'll be back in touch with some initial feedback in the next couple of weeks.

Thank you, Laura

TorontoYYZ commented 3 months ago

Hello again @TorontoYYZ,

In the meantime, I've invited you to join us here on GitHub as an Outside Collaborator. This will give you the Write access you'll need to edit your lesson directly. Charlotte has shared some notes above about a few components that are still needed / details that we'd like to help clarify.

The French original lesson was published before we introduced alt-text for all figures, so I realise that you don't have the original alt-text available to translate. For writing the alt-text, this resource may be useful. It advises that the alt-text for graphs and data visualisations should consist of the following:

alt="Chart type of data type where reason for including chart"

You can either add the alt-text into the templates Charlotte created, or leave a comment here in the Issue and we will add it in for you.

Thank you, Anisa

Thank you for clarifying, Anisa. Could you add the alt-text in for me, please?

Thank you, Christina.

TorontoYYZ commented 3 months ago

I noticed a couple things while processing this submission, which I've outlined below:

  • [x] I wonder whether you'd like to choose between either 'Calibrating carbon ages in R' or 'Calibrating Radiocarbon Dates with R'. Currently, both translations are used interchangeably, but I feel it would be clearer to keep to one of these phrases only.

C: Thank you for noticing! Let's change all the variants to 'radiocarbon date'/'radiocarbon dating' to be specific. That is, 'carbon ages,' 'carbon dates,' 'radiocarbon ages' should all change.

  • [ ] You'll see that I've set up the images using our liquid syntax format : {% include figure.html filename="file-name-1.png" alt="Visual description of figure image" caption="Figure 1. Caption text to display" %}. In most cases, you had provided a caption, which I was able to fill in. However,
    • Figure 8 was missing its caption. I've left the French caption as a placeholder, but I'll leave it to you to translate it to English!

C: Sorry about that, and thank you for explaining what you did - here's the translation for the caption. "Distribution of conventional and calendar dates of the mean ages of samples 2, 3 and 4. The dark gray areas correspond to the 95% HPD interval. IntCal20 calibration curve." I have included this in the .txt file linked in the next comment.

  • All of the figures now also need alt-text – a visual description of the image for visually impaired readers

C: alt text for all figures are in this .txt file, thank you:

alt-text-tables-and-figs.txt

  • You noted that Figure 7 was missing Samples 2 and 3 – let me know when this image is ready, and I can add it in for you

C: thank you, working on this now and will update when done.

  • [ ] Endnotes have not been carried over from the FR version yet. If you're planning to use all the same references, I'm happy to do this myself

Could you please do this for me? Thank you very, very, very much! Do carry them over.

  • [ ] Hyperlinks have also not been carried over from the FR version. Again, if you're planning to replicate them exactly, I can add them in myself

C: Yes, could you replicate the hyperlinks exactly? Thank you again.

  • [ ] I noticed the lesson abstract and 'avatar alt' still need to be translated. I've left the FR versions in the YAML header, which you'll be able to translate/adapt as needed.

C: thank you, and my apologies. The translation for the lesson abstract is here. What did you mean by 'avatar alt'?

abstract.txt

  • [x] I carried over all the mathematical notation from the FR lesson. We use a specific format for these (for example, σ is \\(\sigma\\)). This also means you don't need to add images for the longer equations, as I've already embedded them in the text.

C: you're a lifesaver, thank you very much! again!

  • [x] I replaced the Table 1 image with a markdown table, to help keep the page as light as possible

Amazing, thank you! This looks much lighter, you are right of course

Thank you very much for your patience and your work!

C: genuinely, thank you for editing my work! It looks much better already...

anisa-hawes commented 3 months ago

Hello Christina @TorontoYYZ,

I think I wasn't clear in my previous note about what is required for the alt-text element. We're happy to slot in the text for you, but we do need you to draft the descriptions. It's important to say that alt-text should go further than repeating the figure captions -- this is about opening up the visuals to people who use screen-readers.

I shared Amy Cesal's guide to Writing Alt Text for Data Visualization because I think Cesal's 'formula' for describing graphs could be useful. What I think Amy Cesal's guide achieves which is important, is prompting an author/translator to reflect on the reasons for including the graph or visualisation. What idea does this support? What can a reader learn or understand from this visual?

Another resource I've found useful is the Graphs section of Diagram Center's guidance. I think some key points (relevant to all graph types) we could take away from it are:

Following those prompts, (keeping in mind that my absolute novice reading of this line graph is likely lacking) for Figure 1 you might write:

alt="Line graph showing the exponential decay of radioactive atoms over time. The x-axis is labelled Number of Atoms, while the y-axis is labelled Time (half-lives). From a high upper point, the line curves steeply indicating that after two radioactive periods, the number of atoms has reduced to a quarter of the original quantity."

Would you feel comfortable making a first draft of the alt-text for each of the figures? I know this is a bit time-consuming, but I do think it is very worthwhile in terms of making your translation accessible to the broadest possible audience. We would be very grateful for your support with this.


The avatar_alt which Charlotte mentions above is simply the alt-text description of the thumbnail image which represents the lesson (found at upper left of the header ribbon). The original author wrote the following in French to describe the image: Vases, meubles et sujets divers peints dans les tombeaux des rois so we are just asking for your English translation of that.

Thank you, Anisa

TorontoYYZ commented 3 months ago

Thank you for clarifying Anisa, I'm sorry for not understanding before. This is a good exercise to do. Here is the alt-text.txt following Diagram Centre's guidance.

Thank you for explaining what the avatar text is. I cannot see the image very clearly, so here is the French description translated verbatim. "Vases, furniture, and various objects painted in the tombs of kings." Does it look like the word on top of that image says "Thèbes" to you? If so, we can add that to the text too.

Cheers, and thanks for your patience, Christina

charlottejmc commented 3 months ago

Hi @TorontoYYZ,

Thank you very much for your response! I've added in the translated lesson abstract and the caption for Figure 8, as well as carried over the endnotes and hyperlinks. (Just seeing your comment above: your translation of the avatar is perfect. I'll add it in now.)

I've also renamed the lesson file and image filenames to calibrating-radiocarbon-dates-R to follow the updates title, 'Calibrating Radiocarbon Dates with R'.

Thank you!

TorontoYYZ commented 3 months ago

Charlotte, thank you! Here's a translation of the endnotes. endnotes.docx. Endnote #11 in the French version actually has a time-dependent statement based on the time this lesson was originally published so I added this in brackets. I hope that's clear. At the moment of this lesson’s publication (in French), the curve IntCal20 has just been published. Reimer et al., 2009, 2013, 2020.

lachapot commented 3 months ago

Thank you @TorontoYYZ, @charlottejmc, and @anisa-hawes for all the work you’ve done on this lesson translation so far. We know a lot of people would be very interested in having this lesson available in English so we’re excited that you’re undertaking this, Christina! Here is some additional feedback from @digitalkosovski and me.

The main comment we’d have is that currently the translation feels very literal, following the French nearly word for word, which often makes it hard to read and understand in English. We’d suggest that you go over the translation (without looking at the original French) and revise it to make the language clearer and more idiomatic in English — focus on how you’d want to write it in English to make it easily readable for English readers, rather than following the French so closely. We’d suggest that you pay particular attention to:

We’ve flagged up a few specific instances below, for each section of the lesson, that would need some further attention, and we’ve sometimes provided examples of how you might reformulate, in case that’s helpful, but we leave it up to you to go through the lesson and revise how you see fit to make it clearer, more flowing and idiomatic.

N.B. When paragraph numbers are mentioned they refer to the lesson preview

The abstract

Calibrate Radiocarbon Dates with R

The Principles of Carbon Dating

Why Calibrate Radiocarbon Ages?

How to Calibrate?

Applications with R

How to Visualize the Output Data

Are the Results from Different Laboratories in Agreement?

Date Calibration

How to Interpret these Dates

How to Present your Results

Conclusion

We hope this is helpful! Let us know if there’s anything you’d like to discuss or if you have any questions. Ideally, this first round of revisions would happen within 30 days so that we can move swiftly on to the next phase, but let us know if there are any adjustments you need to make on the timeline.

Thanks again for this exciting contribution and looking forward to working on this with you!

Laura and Agustín

anisa-hawes commented 3 months ago

Hello Christina @TorontoYYZ,

What's happening now?

Your lesson has been moved to the next phase of our workflow which is Phase 3: Revision 1.

This phase is an opportunity for you to revise your draft in response to @lachapot and @digitalkosovski's initial feedback.

You already have the 'write access' you need to edit your draft directly.

We ask authors to work on their own files with direct commits: we prefer you don't fork our repo, or use the Pull Request system to edit in ph-submissions. You can make direct commits to your file here: /en/drafts/translations/calibrating-radiocarbon-dates-R.md. Remember @charlottejmc and I can help if you encounter any practical problems!

When you, Laura and Agustín are all happy with the revised draft, we will move forward to Phase 4: Open Peer Review.

%%{init: { 'logLevel': 'debug', 'theme': 'dark', 'themeVariables': {
              'cScale0': '#444444', 'cScaleLabel0': '#ffffff',
              'cScale1': '#882b4f', 'cScaleLabel1': '#ffffff',
              'cScale2': '#444444', 'cScaleLabel2': '#ffffff'
       } } }%%
timeline
Section Phase 2 <br> Initial Edit
Who worked on this? : Editors (@lachapot + @digitalkosovski) 
All  Phase 2 tasks completed? : Yes
Section Phase 3 <br> Revision 1
Who's working on this? : Author (@TorontoYYZ)  
Expected completion date? : June 30
Section Phase 4 <br> Open Peer Review
Who's responsible? : Reviewers (TBC) 
Expected timeframe? : ~60 days after request is accepted

Note: The Mermaid diagram above may not render on GitHub mobile. Please check in via desktop when you have a moment.

TorontoYYZ commented 3 months ago

Okay, thanks you! I've read your messages. Thank you very much for going through the lesson minutely, and for explaining the next steps.

Could I update the lesson by June 30? I am away from my desk for a few days now.

Cheers, Christina

Get Outlook for Androidhttps://aka.ms/AAb9ysg


From: Anisa Hawes @.> Sent: Friday, May 17, 2024 4:05:46 AM To: programminghistorian/ph-submissions @.> Cc: Christina Nguyen @.>; Mention @.> Subject: Re: [programminghistorian/ph-submissions] Calibrating Radiocarbon Dates with R (translation from french) (Issue #603)

Hello Christina @TorontoYYZhttps://github.com/TorontoYYZ,

What's happening now?

Your lesson has been moved to the next phase of our workflow which is Phase 3: Revision 1.

This phase is an opportunity for you to revise your draft in response to @lachapothttps://github.com/lachapot and @digitalkosovskihttps://github.com/digitalkosovski's initial feedback.

You already have the 'write access' you need to edit your draft directly.

We ask authors to work on their own files with direct commits: we prefer you don't fork our repo, or use the Pull Request system to edit in ph-submissions. You can make direct commits to your file here: /en/drafts/translations/calibrating-radiocarbon-dates-R.mdhttps://github.com/programminghistorian/ph-submissions/blob/gh-pages/en/drafts/translations/calibrating-radiocarbon-dates-R.md. Remember @charlottejmchttps://github.com/charlottejmc and I can help if you encounter any practical problems!

When you, Laura and Agustín are all happy with the revised draft, we will move forward to Phase 4: Open Peer Review.

%%{init: { 'logLevel': 'debug', 'theme': 'dark', 'themeVariables': { 'cScale0': '#444444', 'cScaleLabel0': '#ffffff', 'cScale1': '#882b4f', 'cScaleLabel1': '#ffffff', 'cScale2': '#444444', 'cScaleLabel2': '#ffffff' } } }%% timeline Section Phase 2
Initial Edit Who worked on this? : Editors @. + @digitalkosovski) All Phase 2 tasks completed? : Yes Section Phase 3
Revision 1 Who's working on this? : Author
@.) Expected completion date? : June 17 Section Phase 4
Open Peer Review Who's responsible? : Reviewers (TBC) Expected timeframe? : ~60 days after request is accepted

Note: The Mermaid diagram above may not render on GitHub mobile. Please check in via desktop when you have a moment.

— Reply to this email directly, view it on GitHubhttps://github.com/programminghistorian/ph-submissions/issues/603#issuecomment-2116981864, or unsubscribehttps://github.com/notifications/unsubscribe-auth/ACIZSOHM4KIOTZ5FZRRA75LZCW25VAVCNFSM6AAAAABE5Z5S3OVHI2DSMVQWIX3LMV43OSLTON2WKQ3PNVWWK3TUHMZDCMJWHE4DCOBWGQ. You are receiving this because you were mentioned.Message ID: @.***>

lachapot commented 3 months ago

Hi Christina @TorontoYYZ, thank you for letting us know. June 30th sounds good to me. Have a good break! Laura

TorontoYYZ commented 1 month ago

Hi Laura and Agustín, I've committed the changes directly. Thank you very much for all the corrections; it improves the flow of the lesson considerably. I have so much respect for you who deal with coding, and translation, and technical guides all at once, and with such apparent ease!

I have left some of the very technical translations as they are, e.g. paragraph 20, as they are a step-by-step literal process. I also unfortunately couldn't tell which paragraph number refered to what in the lesson preview (probably my inability to use the GitHub interface), so these are my best guesses for the locations of corrections.

Please let me know when there are any other changes to be made, of course. I'm sorry if I missed something or misunderstood something else. Tell me if that happened!

Christina

charlottejmc commented 1 month ago

Hello @TorontoYYZ,

Thank you very much for all your work updating your lesson. I've gone through the changes you made and ticked them off Laura's comment above.

You'll see that certain boxes are left unchecked – I've copied them below with the line number from the markdown file, to help you see where exactly in the text they refer to:


@TorontoYYZ, perhaps you might want to have another look through these, and decide whether you still want to change anything?

I will also be copyediting and typesetting your lesson later in Phase 6 – so I'll be able to catch and edit any remaining issues.

Thanks again for your great work and your patience!

TorontoYYZ commented 1 month ago

Got it, I'll be on this today or tomorrow... Thanks.

TorontoYYZ commented 1 month ago

Thanks, I've corrected and pushed the changes now. Again thank you for picking through and providing lots of help. :)

lachapot commented 1 month ago

Thank you very much Christina @TorontoYYZ for your kind words and for your hard work on this lesson! And thank you Charlotte @charlottejmc for checking over the edits. We agree that it reads much better now and is nearly ready for the next stage. There are just a few small typos that we might want to address before peer-review:

We noticed there are exclamation marks in some places rather than full stops. Not sure if these are typos or stylistic choices. The exclamation marks feel a little incongruous with the overall style of the piece though so perhaps they should be changed to full stops. They are at:

We also think the expression “the R language” sounds a little strange in English and recommend changing it simply to “R” (as you have already done in many other parts of the lesson). These instance are at:

Otherwise there are just a few small typos and errors:

Once these have been addressed, we’ll be ready to move on to the next phase of external peer-review.

Let us know if you have any questions and thanks again for all your work on this lesson! Laura and Agustín

TorontoYYZ commented 1 month ago

Laura and Agustín, fixed! Thanks for the help. Hooray for the next phase! I apologize for not @lachapot you when I previously posted replies.

lachapot commented 1 month ago

Perfect, thank you for making the edits Christina @TorontoYYZ (and no problem at all about tagging me). The lesson is ready to move on to the peer-review phase now! Anisa @anisa-hawes will provide some further details about this peer-review phase, and Agustín and I will be in touch once reviewers have been confirmed. Thanks again for all your work so far and looking forward to next steps!

anisa-hawes commented 4 weeks ago

Hello Christina @TorontoYYZ,

What's happening now?

Your lesson has been moved to the next phase of our workflow which is Phase 4: Open Peer Review.

This phase is an opportunity for you to hear feedback from peers in the community.

Laura @lachapot and Agustín @digitalkosovski will invite two reviewers to read your translation, test the code, and provide constructive feedback. In the spirit of openness, reviews will be posted as comments in this issue (unless you specifically request a closed review).

After both reviews, Laura and Agustín will summarise the suggestions to clarify your priorities in Phase 5: Revision 2.

%%{init: { 'logLevel': 'debug', 'theme': 'dark', 'themeVariables': {
              'cScale0': '#444444', 'cScaleLabel0': '#ffffff',
              'cScale1': '#882b4f', 'cScaleLabel1': '#ffffff',
              'cScale2': '#444444', 'cScaleLabel2': '#ffffff'
       } } }%%
timeline
Section Phase 3 <br> Revision 1
Who worked on this? : Author (@TorontoYYZ)
All  Phase 3 tasks completed? : Yes
Section Phase 4 <br> Open Peer Review
Who's working on this? : Reviewers (TBC)
Expected completion date? : ~60 days after request is accepted
Section Phase 5 <br> Revision 2
Who's responsible? : Author (@TorontoYYZ)
Expected timeframe? : ~30 days after editors' summary

Note: The Mermaid diagram above may not render on GitHub mobile. Please check in via desktop when you have a moment.