Vocabulary

Editions and the engine

action-translation

QuantEcon's translation engine, also called the engine. It uses an AI model to translate the English lectures, and it opens the sync pull requests that bring later English changes to the editions. See How action-translation works.

Edition

A translated copy of one English lecture series in one language. Each edition has its own repository on GitHub and its own website. For example, QuantEcon/lecture-python-programming.ja is the Japanese edition of Python Programming for Economics and Finance.

Source repository

The repository of an English lecture series, such as QuantEcon/lecture-python-programming. Also called the English repository.

Upstream

The English side of the process: the source repository and its lectures. A correction made upstream reaches every edition. See Errors in the English.

Downstream

The editions. Changes flow from the English lectures, upstream, to the editions, downstream.

Engine release

A numbered version of action-translation. The title of each review pull request names the release that drafted the lecture. The engine's repository lists every release.

Glossary

The engine's list of terms for one language, with the form to use for each. Each glossary is a file in the engine's repository, such as glossary/ml.json for Malayalam. See Terms and house style.

House style

The rules for writing in one language, such as register, punctuation and spacing. Your language page records them.

Phases and rounds

Initial translation phase

The first phase of an edition. Lectures are drafted and reviewed one at a time, and each review improves the engine before the next lecture is drafted. See How an edition is built.

Round

One lecture's cycle in the initial translation phase: draft, review, approval, merge and engine improvement. See How a review round works.

Draft

A lecture as the engine translated it, before review. A lecture stays a draft until its review pull request is merged.

Review pull request

The pull request that carries the draft of one lecture for review. You review it and approve it, and @mmcky merges it. See Reading a review pull request.

Preview

The edition's website built from a pull request, so that you can read a lecture as readers will see it. An automated comment on the pull request links to it.

Review issue

An issue for one lecture, assigned to its reviewer. Its title names the lecture's file, for example Review: python_by_example.md. The merge of the lecture's review pull request closes it. See Find your work.

Project tracker

The issue that @mmcky keeps for an edition, listing its review issues as tasks in the order they are reviewed. It is for organising the work and reporting on it. Reviewers need only their assigned review issues.

Follow-up issue

An issue in the edition's repository for the questions that a review raised. The questions are numbered, and you answer them by number. The Japanese edition's REVIEWING.md calls it a Decision issue. See After your review.

Sync phase

The phase after the initial translation. Changes to the English lectures reach the edition as sync pull requests.

Sync pull request

A pull request that action-translation opens in an edition's repository after a change to an English lecture is merged. It carries the translated change, and its title contains [translation-sync]. The review process for sync pull requests is still being designed. See Sync reviews.

On GitHub

Pull request

A proposed change to a repository. It has its own page on GitHub, where people comment on the change, review it and then merge it.

Issue

A page in a repository for one task or question, where people discuss it until it is closed.

Suggestion

A change to one or more lines that you write in a review comment with Insert a suggestion. @mmcky applies your suggestions as you wrote them. See Reviewing on GitHub.

Approve

The option you choose when you submit a review, to say that the pull request is ready. When your review is complete, you approve the pull request and mention @mmcky in the summary.

Merge

To accept the changes in a pull request into the edition. During the initial translation, @mmcky merges every pull request.

Co-author credit

When @mmcky applies your suggestions, the commit names you as a co-author. GitHub shows you on the commit, and the credit stays after the merge.

translation: block

The block at the top of each translated file. It holds the translated title and the heading map, which the engine uses to match each section with its English section. You can skip it. If you change a heading, @mmcky updates its line in the block. The engine's documentation explains heading maps.

People

Reviewer

Anyone who reviews a lecture, whether an editor or a translator.

Editor

The editor of record for a language: the reviewer who settles questions of terminology and house style with @mmcky. A language has at most one editor, who covers all of its editions.

Translator

A reviewer who reviews lectures, suggests changes and answers questions about terms. A language can have several translators.

Maintainer

Matt McKay, @mmcky, who drafts the lectures, applies reviews, improves the engine and merges pull requests. See Who does what.