Terms and house style

Why this comes first

The engine follows its glossary and its rules for your language when it drafts a lecture. A ruling reaches only the lectures drafted after it. A term settled late would have to be corrected in every lecture already merged. So the main questions are settled before the first draft.

Glossary review

A language's glossary is a file in the engine's repository: a list of terms, with the form the engine uses for each. The file is named after the language code, such as glossary/ml.json for Malayalam.

A new glossary is reviewed on a pull request in the engine's repository. Organise your review in three parts:

• a table of suggested changes, each with a reason;
• a table of terms to keep in English;
• questions for the other reviewers.

Give a source for each change where you can. @mmcky then applies the agreed changes to the glossary. The Japanese glossary was reviewed this way on action-translation#69. It goes live as glossary/ja.json when that pull request is merged.

Numbered questions

Some points need a ruling: terms that the glossary review left open, and questions of house style such as register or punctuation. @mmcky collects these as numbered questions, usually on one issue.

• The questions cover only what a native speaker can decide.
• Each question shows the options in full sentences and gives our guess.
• Answer by number, in one comment.
• Partial answers are welcome.

For an example, see the Japanese questions on action-translation#337. They are numbered T for terms, H for house style and C for consistency.

Questions sent as a file

Sometimes the questions come as a file instead of on GitHub. Type your answers into the file and return the file itself, as plain text. Do not copy the text into Word or Google Docs: they can remove invisible characters that some scripts need, such as the joining characters in Malayalam.

Your own translation

If you have translated a lecture yourself, tell @mmcky. Your translation can become the reference that the engine's drafts are measured against.

Where rulings are recorded

Each ruling is recorded in two places:

• on your language page, in its house-style section and its rulings log;
• in the engine, as a glossary entry or a rule, so that every later draft follows it.

Language pages are ready for Japanese and Malayalam.

If a rule seems wrong

Sometimes a ruling seems wrong when you see it in a later lecture. Say so on the pull request, with a reason and, if you can, a source. The point is then settled once, and the new ruling applies to every lecture that follows.

Sources

Good sources for a term are:

• the official Python documentation in your language, where it exists, for programming terms;
• Wikipedia in your language, for terms in economics, mathematics and statistics;
• standard textbooks and dictionaries.

Asking colleagues is fine too. Do not use AI tools or machine translation to choose a term: see Review by hand.