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.
(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)
This is the draft for the chapter - PR made by Alejandro
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:
… blurb about Transifex, how to sync a new resource, ect…
… discussion about how to view the translated output…
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.
It is key to set translation norms. These norms will guide new comers how to translate and review in the translation platform.
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.
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.
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.
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.
---
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.
---
These rules are essential to harmonise and standardise translations. Make sure you read them before you start translating for the first time.
In each co-working or external session, prioritise those chapters that are close to completion
end of the draft
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)
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?
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
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!
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:
When starting a new language translation, there are several aspects to consider apart from setting up a project in the choosen localisator plaform.
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.
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.
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.
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.
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.
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.
These rules are essential to harmonise and standardise translations. Make sure you read them before you start translating for the first time.
In each co-working or external session, prioritise those chapters that are outdated or close to completion.
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:
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.
[name=Batool] I created a new branch and added the text for localisation:
Please add the landing page in it - I created a blank one
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 :)
next steps?
#welcome=
class: tip
Batool How can we fix toc
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.
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
_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==
We need to know and test many things:
Comparison human-verified version (HT) vs machine-translation (MT):
_
.Filename == binder_comic
Filename == change_stage_repo
Upload a po file from transifex
Upload a md file from transifex
%three\_letters\_code%
(spa, fra, por)Actions
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:
- A meta-issue with all the places that discussion takes place: https://github.com/alan-turing-institute/the-turing-way/issues/967
- 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
- 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
fetch
Andrea's notes:
netlify.toml
overrides whatever configuration we do on the page. We can add netlify.toml files in several subfolders of the same repo: https://docs.netlify.com/configure-builds/common-configurations/monorepos/\_toc.yml
to each language subfolderBatool Crowdin Context-based translation feature
Batool Don't translate certain strings
Alejandro and Batool Discuss submodule
Discussing about next steps:
/website
Recap
Ideas
Admin
Overview
Configuration
Experiments
Actions
bash scripts/multilingual_make.sh
in Makefile builds the transifex po filesWe 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
Solution: remove --overwrite
in multilingual_make.sh
requirements.txt
.
/opt/build/repo/book/content/locale/es/locale/zh_CN/
TTW_spanish_transifex
jinja2.exceptions.TemplateNotFound: basic.tpl
is to run pip install --upgrade nbconvert==5.5
ghp-import -n -p -f _site/es
: this builds the spanish folder in GitHub pages, however it lacks of a landing .Next steps:
Next steps:
Recap Batool's work on crowdin and Alejandro and Camila's progress on transifex deployment.
Call for translators! We're looking for translators to help translate this spec for everyone!(in the REDAME and landing page)
TODO (the last attempt?):
@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; */
}
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
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
Governace
thanks to batool
how can we improve documentaiton and workflows to be able to work efficitnely async and with the new members
batool: