Try   HackMD

Developing the Translation in The Turing Way

Initial preparation by Batool

Work:

  • Deployment
    • How should we deploy the translated version?
    • Look into the experience of the Carpentries
    • Add issue about it in the Jupyter Book repo
    • Maybe experiment with it in a forked or even imported repo
  • Making the workflow easier
    • Adding a GitHub action to make sure the updated version of the book is the one being translated not old one
    • Consider using Crowdin
    • Solutions for ML
    • Improving Glossary
    • Sharing Translation Memory
  • Documentation
    • Use GIFs and examples
    • Document
      • Why use localisation platform?
      • Adding new language
      • Adopting the workflow for Jupyter Book
      • How to start translating
      • How to use ML
      • How to use Glossary
      • How to share the Translation Memory
      • How to approve translation

People to discuss with:

  • Tony
    • The one who set-up the current worksflow
  • Chris
    • maintainer of the Jupyter book/ also in TW Slack
  • Yani regarding the deployment for Translation in Carpentries
    • She has extensive experience with Translation/ also in TW Slack

Guidelines for contributing to this HackMD:

  • Add your name for any comment you add to the HackMD
    e.g. Batool Notes
  • Record the discussion/meetings everyday in this HackMD

Time/Session

Batool: I will join daily in the morning session 8:00-11:30am London time but will try to join other sessions if I can.

Andrea: I will join every day in the 4th session, and try to make it to the third when I can

Alejandro: I will join from 9th November. It suits more for me evening sessions, 17:00-19:00 London time, but I'll try to join other book dash sessions if I can.

Day 1

  • Andrea I read the transifex documentation, the explanation about PO files, and the important issue, 767. Noted down some things in Documentation

Documentation

(Some ideas after reading the Carpentries Spanish and Japanese documentation, and thinking about the Metadocencia experience in translating Teaching tech together, and Wikipedia translation process)

  • Translation is also a community-building task. Nobody should (aim to) do the translations alone because it's long and hard and the task runs the risk of being incomplete :/ BUT with good documentation, people should be able to pick up where the last contributors left, or join them :)
  • Potential members of the translation team are people who are motivated to use the tools, and the outreach during/after with a larger community of native speakers is everything
  • Every language team would have to go through language-specific steps, such as deciding what not to translate, setting up a glossary (or deciding to use one, such as the Carpentries glosario, and deciding to have one translator per section. I am sure Alejandro and the rest of the translation teamand people like Laura and Yaninacould give some further insight with this.
  • A key step for being global The Turing Way

Day 2

  • Batool When the English version is updated, the version on transifex is not updated automatically and this creates a lag between the versions. Then a rebase is needed to update the version on the translation branch.
  • Batool I opened a new issue to track our work here.
  • Batool I have set-up a meeting with Yani and Camila - both have experince in Translation
  • Created a new issue to track the work
    • I think we need to start working on the PR for documention today (maybe open new HackMD to work in the PR), which Alejandro started.
    • We should make sure every language is hotsted in one branch - so we can configure our domain to host each branch at a different sub-domain corresponding to different languages
      • See my discussion with Sarah Gibson here
      • I think we need to fix this hopfully by the end of today so tomorrow, we can possibly focus on the writing.
      • I'm setting up a new workflow in Crowdin in a fork beacuse:
        • It's more open-source friendly
        • Correct the current pipline
        • Collect feedback from Camila

2.1 Meeting with the Spanish Translation team [Pamela, Alejandro]

  • Batool showed us the repository and crowdin options
  • Pamela: currently it's convenient, if the work is not lost it can be ok
  • Which is the branch structure that should work for many languages?

Book Dash, 17:00 - 19:00

  • Batool
    • Crowdin Features highlight
    • Translation memory
    • Glosaries
    • Machine translation
    • Marketplace
      • Translate images (scribera), slides
        • Transifex charges for premium plugins even for open-source projects
    • Workflow
  • Andrea
    • Chapter Outline

Actions

  • Batool: book a slot with a Scribera artist
    • Andrea: Image showing the translation community building? What goes on in github/crowdin/where do the translators and reviewers step in/back to github and netlify.
    • The file structure, if the translations live in a sibling folder next to /website and each language is a subfolder, with chapters as subsubfolders (like the guide/chapter/subchapter image)

This is the draft for the chapter - PR made by Alejandro


Translating The Turing Way

Using Transifex as translation platform

The translation process is done on the Transifex platform. To access the platform open an account and contact the The Turing Way management team to get access to the project.

In Transifex you can have 3 different roles:

  • Translator
  • Reviewer
  • Coordinators (in this role you can both review and translate)

How to sync a new resource on Transifex

blurb about Transifex, how to sync a new resource, ect

How to visualise the translated output

discussion about how to view the translated output

Starting a new language translation

Request a new language on Transifex

In the The Turing Way translation dashboard you can check out the existing languages being translated. If you do not see the language you are interested on you can request for a new language in a tab in the bottom right of the page.

Define norms of translation

It is key to set translation norms. These norms will guide new comers how to translate and review in the translation platform.

Create a dedicated slack channel

We recommend you to create a dedicated slack channel for the language you are translating within the The Turing Way slack. This space will allow you to bring chat with interested parties in your own language.

Organise co-working calls

We suggest to define co-working calls to progress on the translation. These sessions should be open to anyone interested in participating.

You can also work on the translation in the co-working calls of The Turing Way project. You can find this activity in The Turing Way calendar. Please note that these calls are in English.

Asynchronous translation:

Everyone interested in participating in a translation effort should be able to work asynchronously, have this in mind when writing the translation norms and any other documentation for your language.

Translating an existing language

Before you start translating:

The Transifex translation platform looks like the screenshot below. On the left are the text blocks to be translated and on the right is the translation box. You can select with the cursor which block to translate.

We recommend that you look at a translated chapter before you start translating to familiarise yourself with the process and the translation style.

---
height: 400px
name: translation-transifex
alt: Screenshot of the Transifex platform showing the translation of a chapter from English UK to Spanish.
---

Translation tools

We recommend using DeepL as a translation tool. The translation platform of DeepL looks like in the screenshot below. On the left are the blocks of text to be translated and on the right is the translation box.

Tip: When you click on one of the translated words, the tool recommends a series of synonyms. These can be useful especially with long texts.

---
height: 400px
name: translation-deepl
alt: Example of a translation in DeepL from English UK to Spanish.
---

Read the translation rules

These rules are essential to harmonise and standardise translations. Make sure you read them before you start translating for the first time.

Priority list of chapters to translate

In each co-working or external session, prioritise those chapters that are close to completion


end of the draft

Day 2 1/2

HI :wave: in preparation for Wednesday I did something I hope is not problematic, I added Portuguese and made prints of all the steps of adding a new language. (It's the only way to add a language I can help without disrupting the Spanish workflow)

Click on target languages
Add the selected language

As you can see right now it does not have an assignee. @1PPG0ptkTeW_qYfRy5S42Q I could not find where should assign myself :grimacing: could you hekp me with that?

Day 3

  • Alejandro downloaded a sample .pot and we are checking how crowdin would receive the spanish translated files
  • Click on the file -> the whole md is displayed
  • Click on translat
  • Click on Proofreading -> you get the split view with the source and the translation side to side
    How do we migrate?

git rebase of the translation branch. some insights: the ideal would be that the translation could pick up from main because it needs to stay updated. BUT


Workflow for translation within TTW

By translation workflow, we do not refer only to the phases that contributors should follow during the translation process. Instead, we refer to a set of key and optional aspects which can lead to a succesful and sustainable translation project. The translation process can be grouped into four distinct stages. Let's jump in each of them!

  1. Before translation
  2. Starting a new language translation
  3. During translation
  4. After translation

Before translation

Building a new translation project is an exciting way to contribute towards a global The Turing Way. Before starting a translation project, it remains relevant to reflect upon the following questions:

  • Which are your expectations with a translated content?
  • What are the expectations of the target audience?
  • Do you see the target language in the localisator platform?
    • Check out within the existing languages being translated.
    • Reach out existing translation teams and ask them good practices.

Starting a new language translation

When starting a new language translation, there are several aspects to consider apart from setting up a project in the choosen localisator plaform.

Define norms of translation

It is key to set translation norms. These norms will guide new comers how to translate and review in the translation platform. For instance, we strongly suggest to set a [glossary] through the localisator platform.

Create a dedicated slack channel

We recommend you to create a dedicated slack channel for the language you are translating within the The Turing Way slack. This space will allow you to bring chat with interested parties in your own language.

Organise co-working calls

We suggest to define co-working calls to progress on the translation. These sessions should be open to anyone interested in participating.

You can also work on the translation in the co-working calls of The Turing Way project. You can find this activity in The Turing Way calendar. Please note that these calls are in English.

Asynchronous translation:

Everyone interested in participating in a translation effort should be able to work asynchronously, have this in mind when writing the translation norms and any other documentation for your language.

During translation

Before you start translating:

Localisator platforms integrate different tools and formats for assisting the translation process. For instance, Transifex includes the targt text blocks to be translated on the left and a translation box on the right. You can select with the cursor which block to translate.

We recommend that you look at a translated chapter or section before you start translating to familiarise yourself with the process and the translation style.

Machine translation / Translation tools

The translation process can be assisted by machine translation. Localisator platforms such as Crowdin are integrated with well-known machine translation providers including Google, Microsoft, etc. In contrast, for Transifex, this process is performed outside the platform. In this particular case, we recommend using DeepL as a translation tool. DeepL tool recommends a series of synonyms when you click in the translated text. These can be useful especially with long texts.

Read the translation rules

These rules are essential to harmonise and standardise translations. Make sure you read them before you start translating for the first time.

Priority list of chapters to translate

In each co-working or external session, prioritise those chapters that are outdated or close to completion.

After translation

As the Turing Way content grows, the translated content does too. In this regard, we strongly encourage to monitor the TTW content. While updates of the translated content might change according to the availability of resources, it is a good practice to:

  • Have periodical reviewings.
  • Improve the translation
  • Update glossaries

Localisation platforms and translation

Localisation involves more than just translation, which only transforms text. Localisation addresses other factors such as text length and cultural references. A Translation Management System (TMS) manages the localisation process from the beginning of a translation process until the finished product. They are widely used in Open source projects because they offer many advantages such as workflow, automation, transparency, and fast project delivery.

Features of Translation Management System (TMS):

  • Translation Memory
    Translation Memory can be described as a database of sentences or texts and their translations that can be automatically reused in/outside the project. Translation Memory can be very powerful in ensuring consistent and high-quality translations across different projects.
  • Glossary
    A glossary is a collection of the key terms that are used in the project to ensure consistency. The glossary helps in creating, storing, and managing all the project terminology in one place.
  • Machine Translation
    Machine Translation can speed up the translation process. It provides translation suggestions from automatic translation services like Google Translate and AutoML Translation, Microsoft Translate, and more.
  • Integration with GitHub
    Continues integration is vital for automation in open sources projects. Many localisation platforms offer integration with GitHub, which synchronises source and translation files between your GitHub repository and translation project.
  • Screenshots for the context
    Screenshots provide context to the text for translation. TMS offers the opportunity of attaching screenshots to each of the phrases can provide a visual context to translators
  • QA checks
    Many TMS support QA checks. These can include Spelling and/or grammatical errors, inconsistent placeholders and unbalanced brackets. These QA checks make the translation process smoother for translators.

Examples for localisation Platforms:

  • Transfix
  • Crowdin
  • Lokalise
  • Website
  • Pontoon

[name=Batool] I created a new branch and added the text for localisation:

https://github.com/alan-turing-institute/the-turing-way/tree/doc_translation/book/website/community-handbook/translation

Please add the landing page in it - I created a blank one

  • use git move rather than re-base

Translation is a key step for internationalisation of The Turing Way and any efforts in this regard are really welcome.
Translation teams are usually part of the community and they
Having a translated version of The Turing Way can break a barrier for communication and engage more people onboard, irrespectively from/of their native language and their English fluency.
It may be done via lots of tools
And it is also a community-building task. Nobody should (aim to) do the translations alone because it’s long and hard and the task runs the risk of being incomplete :/ BUT with good documentation, people should be able to pick up where the last contributors left, or join them :)

  • Potential members of the translation team are people who are motivated to use the tools, and the outreach during/after with a larger community of native speakers is everything
  • Every language team would have to go through language-specific steps, such as deciding what not to translate, setting up a glossary (or deciding to use one, such as the Carpentries glosario, and deciding to have one translator per section. I am sure Alejandro and the rest of the translation team–and people like Laura and Yanina–could give some further insight with this.

TODO

  • Write the structure of the Translation chapter
    • Landing page (engaging, motivation) Andrea
    • Localization platforms and translation
      • Batool
    • Workflow for translation within TTW
      • Details Coworking calls
      • Deployment Documentation?
    • Guidelines for new contributors (ways to contribute)
      • Alejandro
  • Collect ideas for the illustration
    • Batool, Andrea and Alejandro
  • Experiment with crowdin as new tool
    • Andrea and Alejandro
    • Create a spanish dummy in transifex
    • Transfer the dummy version to crowdin
  • Are we using PO files or md files?
  • If crowdin will be used, move all the translation from Transifex
  • Deployment with Netlify - Andrea
  • By the end of the Bookdash:
    • have a PR only with .md files for the chapter
    • have different PRs for the translation and deployment part

next steps?

Norms of translations of The Turing Way

Decide what should not be translated for consistency and structural integrity

Filewise

  • Don't translate .css, .jpg files
  • Don't translate file names, _toc.yml
  • (expand)

Stringwise

  • The Turing Way stays the same? But ask how it works with transliteration to different alphabets, like arabic.
  • Python book tags: #welcome= class: tip
  • Relative file paths

Each language team

  • Decide the local variation that will be used (european or brazilian portuguese? check ttt rules for Spanish - they decided not using Argentinean local forms (vos) to favour internationalisation)
  • Use the inclusive language conventions for each language, especially try to replace gendered expressions with more general expressions. This should not hinder screen readability (ex. otra/o in Spanish of French inclusive language tou·te·s are readable?)
  • Avoid latin and try to keep screen readability.

Meeting 22-11-2021

  • Batool How can we fix toc

    • How can we update the translation after changing config files
    • Why is the project suspended?
  • Alejandro review done, fixed some minor typos. appproved changes.

  • Andrea reviewed some typos too. I want to start documenting the workflow for a new language (taking PT) to add to the workflow section that Alejandro was building.

Discussion

  • CI/CD and other tests for the translated version? > ask to Sarah G.

  • We lost the hierarchy when crowdin pushed back - creating flat folder with everything inside:

  • solve TOC

    • Check if removing title fields from _toc.yml solves partially the translation
​# ==== Main Landing Page ============= 
​format: jb-book 
​root: welcome 
​parts: 
​- chapters: 
​# ===== Guide for Reproducible Research ============================== 
- file: reproducible-research/reproducible-research 
​sections: 
​- title: Overview ==#TRANSLATE OR OMIT THIS==
​file: reproducible-research/overview ==#DONT TRANSLATE THIS== 

Meeting 23-11-2021

We need to know and test many things:

  • Fetch and merge forked version: What happens when we fetch upstream from TTW to Batool/TTW? It updates! :tada: :+1:

Comparison human-verified version (HT) vs machine-translation (MT):

  • Target file 1
    • File type: markdown with some text followed by a table (3 columns x N rows)
    • Diagnosis:
      • MT translates all strings including those in Filename
        • solution: don't translate strings with _.
      • The quality seems to be quite variable for MT. For instance, cartoon is translated as Caricatura or dibujos animados.
        • row Filename == binder_comic
          • EN:
            • Cartoon showing using binder to share research
          • SP-MT:
            • Mostrar dibujos animados usando el enlace para compartir investigación
          • SP-HT:
            • Caricatura sobre el uso de binder para compartir resultados de una investigación
        • row Filename == change_stage_repo
          • EN:
            • Cartoon showing staging and committing changes
          • SP-MT:
            • Caricatura mostrando cambios en la etapa y la confirmación
          • SP-HT:
            • Caricatura que muestra el montaje y la realización de cambios

Meeting 30-11-2021

  • Walked Camila around crowdin and github
  • Tests
    • binderhub.md
      • Upload a po file from transifex

        • not feasible - loses format if uploaded directly:
      • Upload a md file from transifex

        • TODO
    • add path structure to crowdin.yml
      • Waiting
        We have it! "book/website/translation/Spanish, Latin America/book/website/collaboration/remote-collab/remote-collab-management.md"
      • We need to change spanish, Latin America and add %three\_letters\_code% (spa, fra, por)
    • ignore toc.yml file in crowdin.yml
      • Waiting
      • We have it! > It looks better with the three letters, but

Meeting 7-12-2021

Actions

  • Email Tony about convering the PO file from transifix to Markdown
  • Andrea mentioned that if we could check if crowdin transforms po to md
    • Batool emailed them but it seems they don't have
  • In the worse case scenario we could think about deploying the transifex translation (but this is not optimal)
  • We need to compare the spanish with the updated version (to match the markdown)
  • We may update the deployed translated version at certian time (e.g. once a month) - then also freeze the previous version (subdomian)
    • Maybe with CI (GitHub action)

Tony e-mail, 29 June 2021

P.S.: DETAILS ON TRANSLATION

To work on a translation, Anna has written a great walk through on Transifex’s interface https://github.com/alan-turing-institute/the-turing-way/blob/translation/translation_guide.md
In general I think it works well that another person review your translation, or review yourself’s translation another day. Transifex also let you raise issues there, as well as show all the past translations. Once a chapter is finished, you can send it to GitHub via Settings -> Integrations -> Send to GitHub and set the threshold to 100 so it would only send fully completed and reviewed chapters.

I opened a few issues to track the progress and discussions:

  1. A meta-issue with all the places that discussion takes place: https://github.com/alan-turing-institute/the-turing-way/issues/967
  2. Discussion on which chapter should take priority, currently we are following the book’s order: https://github.com/alan-turing-institute/the-turing-way/issues/970
  3. Discussion on glossary, for example the name ’The Turing Way’ should stay as is: https://github.com/alan-turing-institute/the-turing-way/issues/969

The current organisation of files is we put all translations on the translation branch first then merge to the master branch once a big chunk is done. It made sense when we started, let me know if you have other thoughts on this. A netlify build is setup on the translation branch, it can be previewed here: https://competent-nightingale-4c1d36.netlify.com/introduction/introduction and translated versions are directed with the language code, such as https://competent-nightingale-4c1d36.netlify.com/zh_cn/introduction/introduction for the Chinese version, https://competent-nightingale-4c1d36.netlify.com/es/introduction/introduction for Spanish. We also need to add a language switch button at some point

Currently the build process of translations uses the original version’s table of contents, which fails when the table of contents is updated (such as now). I’m working on caching a copy of the TOC when the source po files are generated so it’s decoupled from the English version completely. I aim to get that done in the next few days so we can finally merge something into master!

One thing I’m giving a lot thought on is the update of the book. If I understand correctly, when the source po files are updated, all translation strings on Transifex will be removed initially if they do not match up perfectly. Transifex will let you know that a similar string was translated previously or elsewhere then you can repopulate it with one click and modify/review accordingly. I think that’s essentially what happened last week when I rebased the branch. We will give it a go once the above mentioned merge is done.

I hope this is helpful and please let me know if anything is not clear.

Best wishes,
Tony

Meeting 14-12-2021

Tony meeting

Additional resources

Meeting 21-12-2021

Recap :open_book:

Achievements :i_love_you_hand_sign:

  • Alejandro, Andrea, Batool: we were able to run the translated version in arabic, spanish, and portuguese locally. :tada:

  • Spanish translation: in overall looks good but, we should play with the glosary or rules to avoid translating the Turing Way and other key strings. The Turing Way below the logo was translated as La Via Turistica (The Tourist Way) :rolling_on_the_floor_laughing:

  • Arabic Translation is good overall but has the following problems:
    • Alignemnts needs to be corrected especially if there's an English text in the paragraph
    • The font type needs to be changed
    • The tags needs to be ignored

Andrea's notes:

  • Portuguese translation will need guidelines to:
    • decide the variant (Brazilian instead of Portuguese)
    • check the current orthography (Novo Acordo Ortográfico) is used
    • modify some gendered expressions or decide what to do with them
  • about the repo
    • currently each one of us has a fork and a personal netlify account. i cannot set up my netlify in batool's fork because it's not an organization. so i needed to create my own fork from batool's
    • i think we should create a github organization with the three of us so we can work on the same repo and netlify
  • about netlify

TODO :checkered_flag:

  • Push the corrected crowdin.yml
    • keep the translation folder as a child of the website directory
  • Push the translated files to their new location in book/website/translations Andrea
  • Copy a \_toc.yml to each language subfolder
  • try to solve netlify toml configuration (see Andrea note)
    • if we cannot solve it, check with Sarah Gibson

Meeting 18-01-2022

Recap

  • Updates of the crowdin machine translation process
  • We updated to the current version of ttw, the translation should be triggered now
  • Alejandro added toc-yml for Spanish - needs updating.
  • About transifex, Camila talked about the need for editing and making the whole translation more homogeneous
  • Batool There is a problem with the GitHub integration
  • Batool I managed to install Crowdin CLI - Finally - there's cool things we can automate with it

Next steps

  • Deploy the website for the manual translation
    -> meeting with Sarah some time in the next two weeks? Alejandro will check
  • Transfer machine translation repo to a new organisation GitHub account? This would allow us to experiment with netlify -check with Malvika and Sarah about where it is better to put this repo.
  • Push local toc.yml_ files and check if they trigger some error, if they are translated, etc.
  • Batool I think it might be important to collect feedback from the TW community about the MT and what aspects needs to be fixed
  • Batool I am updating the Translation chapter in our PR with everyting about Crowdin
    • More documantation about the different ways to contribute to the translation
    • Using GIFs

Meeting 24-01-2022

Meeting 25-01-2022

  • Batool Crowdin Context-based translation feature

  • Batool Don't translate certain strings

  • Alejandro and Batool Discuss submodule

Meeting 31-01-2022 (w Sarah)

  • discourse: netlify for multiple subdirectories
  • define which the target content for translation
    • images
  • write git history
  • look into the persona work in terms of netlify
  • spanish-translation

Meeting 01-02-2022 (Batool, Andrea)

Discussing about next steps:

  • Try to meet the team that created and deployed the personas
  • Batool transfered the repository to an organization to be able to configure Netlify :tada:
  • We need to find a solution for the images:
    • Another repo? We know it's not the preferred way
    • Maybe with absolute paths instead of relative so that they don't get translated
    • Maybe the figures can be hosted in a folder outside of the book, a sibling folder to /website
    • I will remove the reanslation from Git and re-sync after hiding strings
    • Contact crowdin for in-context and automating strings hiding

Meeting 08-02-2022 (Batool, Alejandro, Andrea)

  • Alejandro Why organisation?
    • Allow deploying Netlify
    • Temporary

Recap

  • solution for the images
    • use url from Zenodo
    • create PR to master english TTW

Ideas

Admin

  • only approved translation, can be push to the translated version
    • all chapter? two-step approval

Meeting 10-02-2022 (Alejandro, Camila)

Overview

Configuration

Experiments

  • problem with the runtime, python 3.7

  • changed to 3.8, deployment start but,

  • building failed still errors :face_with_raised_eyebrow:

Actions

  • Commit was reversed to python 3.7
  • Contact Tony to confirm if the website is hosted in his personal Netlify
  • Ask to share the netlify configuration for deployment

Meeting 15-02-2022 (Alejandro, Batool, Andrea)

  • Andrea and Alejandro will submit a lightening talk in CW22.
  • Alejandro: Recap of the spanish transifex translation deployment
    • TODO: prepare abstract for CW22, deadline: 4 March 2022
      • 1-slide summarising translation efforts
  • Andrea: work on the PR#2202
    • Explore
  • Batool: I think we need to apply the following changes to PR#2202:
    • Mention the translation Guide in the main page - so people would know that there are active work in translationg the book and where to find more information (where is the chapter - it's so hidden)
    • There are no prerequisites for this chapter - Mention that you don't need to know GitHub to contribute
    • Define localisation and internationalisation
    • I love the motivation section
      • want to highlight "Bear in mind you do not need to be fluent in English to contribute to the translations, you only need to speak your own language."
    • In the section for "Examples for Localisation Platforms"
      • I need to make a table and show the free features to compare between the most widespread platforms. I think this is important for people who just started using localisationa and exploring with different platforms.
    • I want to add examples of OS projects which are active in translating their project.
    • Do the features of the localisation makes sense? do you think it's better to elaborate/add images/diagrame!
    • The workflow should be divided into
      • for developer:
      • for contributors:
        • reviwer
        • translator
        • moderator
      • Language-wise guidlines

Meeting 16-02-2022 Andrea

  • I worked a little bit on the PR #2202, rephrased and added some links.
  • Our current content has not a lot of references to our current workflow but since it's work in progress it's hard to set in stone.

Meeting 24-02-2022 (Alejandro, Camila)

Overview

  • We advanced in understading Tony's deployment of Transifex translation files in Netlify.
  • Inspection of key files in Tonny's deployment:
  • Target languages to compile should be declared in LINGUAS. We removed Chinese and TR in the file to only experiment with spanish.

Experiments

Exp 1

We found conflicts between jupyter-book==0.6.4 and Netlify when compiling due to jinja2 not recognising the basic.tpl file (see the screenshot below).

Solution: unpin jupyter book in requirementx.txt

Exp 2
  • The latest jupyter book version doesn't have the overwrite argument.

Solution: remove --overwrite in multilingual_make.sh

Next steps

  • Build the translation branch but in GitHub Pages due potential imcompatabilities between Netlify and packages in requirements.txt.
    • Alternatively, see if we can build a VM in Netlify with same configuration when the translation branch was deployed by Tony.
  • Inspect in more detail Tony's GH repo, https://github.com/tonyyzy/po4jupyterbook, as the compiled markdown files keep chinese abbreviation in the compiled file even the translation is in spanish (es):

/opt/build/repo/book/content/locale/es/locale/zh_CN/

Async - Andrea 08-03-2022

Async - Alejandro 10-03-2022

  • Tested the deployment of the translation branch with transifex files
  • Created a new repo TTW_spanish_transifex
    and copied the translation branch (only the website folder)
  • Installed python 3.8 and run book/Makefile locally
    • make site
  • This run the make file inside book/website/Makefile
    • The solution to th error jinja2.exceptions.TemplateNotFound: basic.tplis to run pip install --upgrade nbconvert==5.5
  • _build and _site folders are generated and contain the html (rendered files)
  • ghp-import -n -p -f _site/es : this builds the spanish folder in GitHub pages, however it lacks of a landing .
  • The introduction webpage of the spanish folder can be visualised here: https://twtranslation.github.io/TTW_spanish_transifex/introduction/introduction.

Next steps:

  • Render html files as a jupyter book?

Meeting 17-03-2022 Camila & Alejandro

  • Recap of latest test in GH actions
  • Attempt to recreate with Netlify
    • Add nbconvert==5.5 in requirements.txt

Next steps:

  • Upload PO translate files and render plain HTML
  • Create a new Markdown file containing links to the rendered plain HTML

Batool

Batool & Alejandro 30-03-2022

Recap Batool's work on crowdin and Alejandro and Camila's progress on transifex deployment.

Next steps

  • Prioritise chapters
    • Non-technical
  • Glossary
    • Ask crowdin how updates in glossary affects translated strings
    • Alejandro Move manual translation glossary in Spanish from Google Docs to crowdin

Batool 5-4-2022

  • Open Science Community Saudi Arabia (OSCSA) will recruit an intern to work on the Arabic Translation from may until August as part of Outreachy
  • I have added a new MT engin to the translation.
  • I changed the workflow - removed automatic MT because of some feedback from new contributors
  • Created a crowdsourcing page for the Turing Way
  • We have a few volunteers doing Arabic translation but they kinda got lost beacuse there are so many files to choose from
  • Since we have TM as 1st step in the workflow which means any strings which has similarities to the strings in TM, it will use it to translate the string. So, if we include the spanish translation in the TM, it will use it 1st to look in any strings that's simmilar and use it for initial translation.
    • We can't use PO files for TM but I found a way to convert it to csv and add it TM. I already added one file and will follow the rest.

Batool 12-4-2022

TODO

  • Add GitHub Action for
    • Copy all importated updated scripts
    • Automate table of content
  • Add Google Translate Engine
  • Add DeepL Translate Engine
  • Add all old Spanish Translation as Translation Memeory
  • Deploy the book
    • Locally
    • Minimum version with only the landing page and bibliography
  • Add webshook to Slack about the translation
  • Update README in crowdsourcing
  • Co-working calls for the Translation
  • Write the chapter
    • Add about the translation in the landing page of The TW book.
    • Call for translators! We're looking for translators to help translate this spec for everyone!(in the REDAME and landing page)

    • Landing page OF Trnslation
      • Everything is OK
      • Introduce what you will learn in the next few pages, developer, start translating TW, ..etc.
      • No knowledge in GitHub is needed
    • Translating Open Source with localisation platforms
      • Add example of Glossary, MT, TM, QA check.
      • Add examples of OS projects which are active in translating their project
        • All-contributor, GitLab,
      • I need to make a table and show the free features to compare between the most widespread platforms. I think this is important for people who just started using localisationa and exploring with different platforms
    • Getting Started Now.
      • These guidlines was inspired by similar Open Source projects localised by the localisation Lab.
      • Create an account in Crowdin
      • Join the translation from this invite link
        • Crowdsourcing
      • Read the landing page of the Turing Way and README to understand the vision and mission of the Turing Way Book.
      • Review the Translation Guidelines.
        • what should not be translated for consistency and structural integrity.
        • It is essential to harmonise and standardise translations. Make sure you read them before you start translating for the first time.
          • Filewise
            - Don’t translate .css, .jpg files
            - Don’t translate file names, _toc.yml
          • Stringwise
            - The Turing Way stays the same? But ask how it works with transliteration to different alphabets, like arabic.
            - Python book tags: #welcome= class: tip
            - Relative file paths
          • Each language team
            - Decide the local variation that will be used (european or brazilian portuguese? check ttt rules for Spanish - they decided not using Argentinean local forms (vos) to favour internationalisation)
            - Use the inclusive language conventions for each language, especially try to replace gendered expressions with more general expressions. This should not hinder screen readability (ex. otra/o in Spanish of French inclusive language tou·te·s are readable?)
            - Avoid latin and try to keep screen readability.
            - Translate according to the context and change punctuation according the langauage
            - Language-specific steps to be developed in the future!
      • Start Translating chapters from the Translation Priorities
        • We are using Crowdin for translation, where you can find how to use it in the next chapter.
        • The prioriry oc chapters are marked inside Crowdin as tasks.
          • These are devided as follow:
            • Urgent (Welcome, afterword)
            • Priority +++ (Overview of the guide of reproducible reaserch, Open Resaerch)
            • Priority ++ (Research data Managemnt, Research Compendia, Licensing)
            • Priority + (Version Control, Overview of Project Design, Creating Project Repositories)
            • Intermediate (Overview of the Guide for Communication, Making Research Objects Citable, Communications in Open Source Projects, Getting Started With GitHub, Research Infrastructure Roles, Introduction to Research Ethics)
    • Demystifying Crowdin!
      • Go through what localisation mean in chapter
      • All translation of the TW is carried out in Crowdin Enterprise, which is aTranslation Management System is Crowdin. Crowdin is integrated to a GitHub fork of The Turing Way in a temporary GitHub Organization. Every time the repository is updated, Crowdin starts an automatic translation. These translations need to be reviewed before imported to the repository. The fork is also kept up date with TW repository atomatically using pull app.
      • As mentioned previously, you can get invited to this through link or crowd sourcing project.
      • Add new langauge (Andrea)
      • Roles (Translator, Proofread, Manger)
      • Workflow steps
      • Crowdin Editor
        • The editor menu has two modes
        • Setting up a Glossary
      • How to use MT
        • Old Transefix Translation
      • How to share the Translation Memory
        • Crowdin will let you know that a similar string was translated previously or elsewhere then you can repopulate it with one click and modify/review accordingly
    • Adopting the workflow for Jupyter Book
    • Translation for TW illustration

  • Crowdsourcing
  • Old translation
  • Glossary
  • Tasks
    • DeepL
    • Prioriety
  • Outreachy
  • Pull automatically
  • Book

Alejandro, Batool & Camila 12-4-2022

TODO (the last attempt?):

Batool 24-4-2022

  • Added the alighnment for the Arabic Book with custom CSS
@import url('https://fonts.googleapis.com/css2?family=Noto+Sans+Arabic:wght@100;200;300;400;500;600;700;800&display=swap');



* {
    direction: rtl;
}

.topbar > div {
    direction: rtl;
    display: grid;
    grid-template-columns: 12fr 3fr 3fr;
}

#navbar-toggler {
    justify-self: right;
}

div .bd-content .section {
    display: flex;
    flex-direction: column;
    align-items: flex-start;
}

p {
  direction: rtl;
  font-family: 'Noto Sans Arabic', sans-serif;

}

body {
  text-align: right;
  font-family: 'Noto Sans Arabic', sans-serif;
}

h1 {
  font-family: 'Noto Sans Arabic', sans-serif;
  font-weight: 500;
  color: blue;

  /* color: #757474; */
}

h2 {
  font-family: 'Noto Sans Arabic', sans-serif;
  font-weight: 400;
  /* color: #757474; */

}

h3 {
  font-family: 'Noto Sans Arabic', sans-serif;
  font-weight: 400;
  /* color: #757474; */

}

  • Added a brife description of Alejandro and Andrea work in OSCSA newsletter

Batool 2-5-2022

  • Added DeepL to Crowdin
  • Add content to the PR on how to get started

Batool 3-5-2022



17-5-2022

8-6-2022 Batool

Batool The deplyment of the Arabic version was carried out in my accunt by changing the netlify settings:
This is the netlify.toml

[build]
  base = "book/translation/ara/book/website"
  command = "pip install -r requirements.txt && jupyter-book build ."
  publish = "_build/html"


# A redirect rule with all the supported properties

[[redirects]]
  from = "/reproducible-research"
  to = "/reproducible-research/reproducible-research"
  # The default HTTP status code is 301, but you can define a different one.
  status = 301
  force = true

[[redirects]]
  from = "/communication"
  to = "/communication/communication"
  # The default HTTP status code is 301, but you can define a different one.
  status = 301
  force = true

[[redirects]]
  from = "/collaboration"
  to = "/collaboration/collaboration"
  # The default HTTP status code is 301, but you can define a different one.
  status = 301
  force = true

[[redirects]]
  from = "/project-design"
  to = "/project-design/project-design"
  # The default HTTP status code is 301, but you can define a different one.
  status = 301
  force = true

[[redirects]]
  from = "/ethical-research"
  to = "/ethical-research/ethical-research"
  # The default HTTP status code is 301, but you can define a different one.
  status = 301
  force = true

[[redirects]]
  from = "/community-handbook"
  to = "/community-handbook/community-handbook"
  # The default HTTP status code is 301, but you can define a different one.
  status = 301
  force = true

[[redirects]]
  from = "/reproducibility/01/*"
  to = "/reproducible-research/overview"
  # The default HTTP status code is 301, but you can define a different one.
  status = 301
  force = true

[[redirects]]
  from = "/reproducibility/02/*"
  to = "/reproducible-research/overview"
  # The default HTTP status code is 301, but you can define a different one.
  status = 301
  force = true

[[redirects]]
  from = "reproducibility/03/definitions"
  to = "/reproducible-research/overview/overview-definitions"
  # The default HTTP status code is 301, but you can define a different one.
  status = 301
  force = true

[[redirects]]
  from = "/reproducibility/04/*"
  to = "/reproducible-research/overview"
  # The default HTTP status code is 301, but you can define a different one.
  status = 301
  force = true

[[redirects]]
  from = "/reproducibility/04/*"
  to = "/reproducible-research/overview"
  # The default HTTP status code is 301, but you can define a different one.
  status = 301
  force = true

[[redirects]]
  from = "/open_research/*"
  to = "/reproducible-research/open"
  # The default HTTP status code is 301, but you can define a different one.
  status = 301
  force = true

[[redirects]]
  from = "/version_control/*"
  to = "/reproducible-research/vcs"
  # The default HTTP status code is 301, but you can define a different one.
  status = 301
  force = true

[[redirects]]
  from = "/licensing/*"
  to = "/reproducible-research/licensing"
  # The default HTTP status code is 301, but you can define a different one.
  status = 301
  force = true

[[redirects]]
  from = "/credit/*"
  to = "/reproducible-research/credit"
  # The default HTTP status code is 301, but you can define a different one.
  status = 301
  force = true

[[redirects]]
  from = "/rdm/*"
  to = "/reproducible-research/rdm"
  # The default HTTP status code is 301, but you can define a different one.
  status = 301
  force = true

[[redirects]]
  from = "/reproducible_environments/*"
  to = "/reproducible-research/renv"
  # The default HTTP status code is 301, but you can define a different one.
  status = 301
  force = true

[[redirects]]
  from = "/code_quality/*"
  to = "/reproducible-research/code-quality"
  # The default HTTP status code is 301, but you can define a different one.
  status = 301
  force = true

[[redirects]]
  from = "/testing/*"
  to = "/reproducible-research/testing"
  # The default HTTP status code is 301, but you can define a different one.
  status = 301
  force = true

[[redirects]]
  from = "/reviewing/*"
  to = "/reproducible-research/reviewing"
  # The default HTTP status code is 301, but you can define a different one.
  status = 301
  force = true

[[redirects]]
  from = "/continuous_integration/*"
  to = "/reproducible-research/ci"
  # The default HTTP status code is 301, but you can define a different one.
  status = 301
  force = true

[[redirects]]
  from = "/make/*"
  to = "/reproducible-research/make"
  # The default HTTP status code is 301, but you can define a different one.
  status = 301
  force = true

[[redirects]]
  from = "/research_compendia/*"
  to = "/reproducible-research/compendia"
  # The default HTTP status code is 301, but you can define a different one.
  status = 301
  force = true

[[redirects]]
  from = "/risk_assessment/*"
  to = "/reproducible-research/risk-assess"
  # The default HTTP status code is 301, but you can define a different one.
  status = 301
  force = true

[[redirects]]
  from = "/binderhub/*"
  to = "/reproducible-research/binderhub"
  # The default HTTP status code is 301, but you can define a different one.
  status = 301
  force = true

[[redirects]]
  from = "/collaborating_github/*"
  to = "/communication/communication"
  # The default HTTP status code is 301, but you can define a different one.
  status = 301
  force = true

[[redirects]]
  from = "/open-source-comms/* "
  to = "/communication/os-comms"
  # The default HTTP status code is 301, but you can define a different one.
  status = 301
  force = true

and also changing the _config.yml as follows:

#######################################################################################
# A default configuration that will be loaded for all jupyter books
# Users are expected to override these values in their own `_config.yml` file.
# This is also the "master list" of all allowed keys and values.

#######################################################################################
# Book settings
title                       : "منهج تورنج"  # The title of the book. Will be placed in the left navbar.
author                      : The Turing Way Community  # The author of the book
copyright                   : "2020-2021"  # Copyright year to be placed in the footer
logo                        : "./figures/logo/logo.jpg"  # A path to the book logo
exclude_patterns            : ["LICENSE.md"]  # Patterns to skip when building the book. Can be glob-style (for example "*skip.ipynb")

#######################################################################################
# Execution settings
execute:
  execute_notebooks         : auto  # Whether to execute notebooks at build time. Must be one of ("auto", "force", "cache", "off")
  cache                     : ""  # A path to the jupyter cache that will be used to store execution artifacs. Defaults to `_build/.jupyter_cache/`
  exclude_patterns          : ["LICENSE.md"]  # A list of patterns to *skip* in execution (for example a notebook that takes a really long time)

#######################################################################################
# HTML-specific settings
html:
  favicon                   : "./figures/logo/favicon-32x32.png"  # A path to a favicon image
  navbar_number_sections    : False  # Add a number to each section in your left navbar
  google_analytics_id       : "UA-167881009-1"  # A GA id that can be used to track book views.
  home_page_in_navbar       : true  # Whether to include your home page in the left Navigation Bar
  extra_navbar              : يمكنك زيارة <a href="https://github.com/alan-turing-institute/the-turing-way">GitHub Repository</a>
    <div>هذا الكتاب تم بناءة بواسطة <a href="https://jupyterbook.org">Jupyter Book</a></div>
  comments:
    hypothesis: true

#######################################################################################
# Launch button settings
launch_buttons:
  notebook_interface        : "classic"  # The interface interactive links will activate ["classic", "jupyterlab"]
  thebelab                  : false  # Add a thebelab button to pages (requires the repository to run on Binder)

repository:
  path_to_book              : "book/website"  # A path to your book's folder, relative to the repository root.
  branch                    : main

#######################################################################################
# Advanced and power-user settings
sphinx:
  extra_extensions          :  # A list of extra extensions to load by Sphinx.
  config                    :  # key-value pairs to directly over-ride the Sphinx configuration
    language                : ar
    dir                     : rtl
    bibtex_reference_style  : label

bibtex_bibfiles:
    - _bibliography/references.bib

In terms of the documentation:

  • I think it should be written clearly in the book

    • Link the chapter to the README of the repo + README of the Turing Way + GitHub TWTranslation account + Main page of the book
    • Langauge-specific Translations (convention specific for the language) should be separeated in a repo by the main translators
    • Add these docs to chapter in the book
  • Aknowledgments

    • Crowdin-bot only acknowledge only the number of words translated

      but we need to show other types of contrbutions such as voting, proofreading, commenting, so I suggest ( not perfect) using this table (for each language in the main page of the translated book):

    • Shall we make our Glossary/TM accessible to other OS projects?

  • Technical challenges

    • I think we might need to clean up the some of the TM that was generated with MT at the very beginning becaues we need delete one of the branches to improve the sync.
    • Where do we do deployment (personal account or TW)?
    • How to deal with cross-referencing?
  • Governace

    • Meetings (volunters, leads, etc)
      • Notes (Public/Privates)
      • Monthly Reports
    • Do grant access to the Glossary to everyone?
    • Divid rules/tasks!
    • Conference partcipations
      • WriteTheDocs

Governance Meeting 8-6-2022

thanks to batool
how can we improve documentaiton and workflows to be able to work efficitnely async and with the new members
batool:

  • new intern outreachy,
  • acknowledgement
  • pre-translation