Start here
How action-translation works
QuantEcon's translation engine, action-translation, drafts the translations. Once an edition is complete, it also keeps the edition in step with the English lectures. This page shows how changes flow down from the English to the editions, and how your reviews flow back.
Upstream and downstream
Each English lecture series has one source repository on GitHub. This is upstream: the lectures are written and changed there. Each edition is a translated copy of a series, with its own repository downstream of the English.
The engine, action-translation, sits between them. It uses an AI model to translate the English and to review translations. It keeps a glossary of terms and a set of language rules for each language it supports, and your reviews improve both.
The diagram shows Python Programming for Economics and Finance and its five editions. The other two English series work the same way, each with a Simplified Chinese edition.
When an English lecture changes
These steps follow the sync path in the diagram.
- A change to the English is merged. Someone opens a pull request that changes a lecture, or the table of contents, in the English source repository. Nothing happens until that pull request is merged into the main branch.
- action-translation finds what changed. It divides the lecture into sections at its headings and compares the old English with the new. To find the same section in your edition, it uses the heading map. This is the
translation:block at the top of each translated lecture, which pairs each English heading with its translation. - It translates only the changed sections. For each changed section, it updates the current translation to match the new English, following the glossary and rules for your language. Sections whose English did not change stay exactly as they are. A new lecture is translated in full.
- It opens a sync pull request in each synced edition. Each edition gets its own pull request. The title contains
[translation-sync]and the title of the English pull request, and the labels includeaction-translationandautomated. The description links the English pull request, so you can see what changed. - It reviews the translation. It posts an automated AI review as a comment, with a verdict (PASS, WARN or FAIL), scores and a few suggestions. It checks terms against the glossary. It does not approve or merge the pull request. The review needs no attention from you.
- @mmcky merges. The review process for sync pull requests is still being designed, and for now @mmcky handles them. If you notice a problem in one, comment on it and mention @mmcky. See Sync reviews.
- Other open sync pull requests are updated. When one is merged, action-translation updates any other open sync pull request in that edition that changes the same lecture.
Two ways a lecture reaches an edition
An edition is built in two phases, and action-translation works differently in each. Today ja and ml are in initial translation, and fr, fa and zh-cn receive sync pull requests.
| Phase | Initial translation | Sync |
|---|---|---|
| A pull request opens | After the previous lecture is merged and the engine is improved and checked | After a change to the English is merged |
| Drafted by | @mmcky, with the latest release of action-translation | action-translation, automatically |
| Translated | The whole lecture | Only the changed sections, or a new lecture in full |
| Human review | You review the whole lecture in a round | Still being designed |
| Merged by | @mmcky, after you approve | @mmcky, for now |
What this means for you
Your corrections teach the engine
After each review, @mmcky adds what your corrections show to action-translation, as glossary entries, language rules and automatic checks. These go into a new release of the engine, and every later draft and sync for your language uses them. See How your review is used.
Errors in the English go upstream
Open a short issue in the English repository, or mention the error on your pull request and @mmcky raises it. Once the English is fixed, lectures drafted later start from the corrected English, and sync carries the fix to every synced edition. See Errors in the English.
For example, the French editor noticed that the text of the English NumPy lecture no longer matched its code, and reported it in lecture-python-programming#594. The English was fixed in lecture-python-programming#595, and sync pull requests then carried the fix to the French, Persian and Simplified Chinese editions.
Add nothing the English does not have
The next sync of a lecture removes any section that the English lecture does not have, and the sync pull request lists it under Target-Only Sections Removed. See Errors in the English.
When your edits survive a sync
A sync changes only the sections whose English changed. Sync reviews explains what this means for your corrections.
If you change a heading in a review, @mmcky updates the heading map, so that later syncs still find the section.
Where things live
All of these are public on GitHub.
| What | Where | Use it for |
|---|---|---|
| English lectures (upstream) | lecture-python-programming, lecture-python-intro, lecture-python.myst | Issues about errors in the English: programming, intro, intermediate |
| Python Programming editions (downstream) | lecture-python-programming.ja, .ml, .fr, .fa, .zh-cn | Review pull requests and follow-up issues |
| Other editions (downstream) | lecture-intro.zh-cn, lecture-python.zh-cn | The Simplified Chinese editions of the other two series |
| action-translation | QuantEcon/action-translation | The engine. Glossary reviews, and some questions about terms, happen here. |
| Glossaries | fa, fr, ml, zh-cn | One file per language, with the terms the engine uses. The Japanese glossary goes live when action-translation#69 is merged. |
| Language rules | Part of the engine's code | The language pages list the rules that affect your review. The Japanese rules arrive with the same pull request. |
| Documentation | quantecon.github.io/action-translation | Technical detail. You do not need it to review. |