Start here
How an edition is built
An edition is a translated copy of an English lecture series. It is built in two phases: an initial translation, reviewed one lecture at a time, and then sync, which carries later changes to the English lectures into the edition.
What an edition is
QuantEcon publishes several lecture series in English. An edition is a translated copy of one series in one language. Each edition has its own repository on GitHub and its own website.
For example, the Japanese edition of Python Programming for Economics and Finance is in QuantEcon/lecture-python-programming.ja. Its English source is QuantEcon/lecture-python-programming. Changes flow from the English repository, upstream, to the editions, downstream. Languages lists every edition.
In the initial translation, each lecture starts as a machine translation by QuantEcon's translation engine, action-translation. Reviewers who are native speakers of the language then correct it. See How action-translation works and Who does what.
Two phases
Initial translation
In the first phase, the edition is built one lecture at a time. @mmcky drafts a lecture with the latest release of action-translation and opens a review pull request. A reviewer reviews the lecture, approves the pull request and mentions @mmcky, and @mmcky merges it. Any questions that the review raises are posted on a follow-up issue. Before the next lecture is drafted, @mmcky improves the engine from the review and checks the improved engine against the merged lecture. Until a lecture is merged, it is a draft.
Each lecture is one round. See How a review round works.
Sync
Once the edition is complete, with every lecture merged, it moves to the sync phase. From then on, each time a change to an English lecture is merged, action-translation translates the change and opens a sync pull request in the edition's repository. Before this phase, changes to the English lectures do not reach the edition automatically.
The review process for sync pull requests is still being designed. See Sync reviews.
The French, Simplified Chinese and Persian editions were published before the review rounds began, and sync pull requests already reach them.
Why one lecture at a time
The engine learns from each review, but a correction reaches only the lectures drafted after it. If every lecture were drafted at once, each draft would repeat the same errors, and you would make the same correction in every lecture.
When lectures are drafted one at a time, each draft starts from everything the earlier reviews taught the engine. Your review of one lecture improves the next.
Why human review matters
Machine translation can read fluently and still say something different from the English. A sentence can be smooth and grammatical, and still reverse the meaning, drop a condition or use the wrong term. Errors like this need a careful reader who knows both languages.
You also judge what only a reader of the language can judge: whether a term is the one your readers know, and whether the wording suits a textbook.
What your review produces
Each review produces three things.
- A correct lecture. Your suggestions are applied to the lecture, and readers of the edition read your version.
- A better engine. Your corrections become glossary entries, rules or automatic checks in the engine, so later drafts in your language need fewer corrections.
- A reference version. The merged lecture becomes a reference version. Later versions of the engine are checked against it.