singe/docs/TRANSLATING.md

# Translating the Books

The three Singe books are kept in English and in French, Italian, German, and Spanish.  The English
is the source:  docs/Manual.adoc, docs/Reference.adoc, and docs/Learn.adoc with the lessons in
docs/lessons/.  Each language has the same files under docs/fr, docs/it, docs/de, and docs/es, plus
locale.adoc (the captions Asciidoctor prints:  Chapter, Table of Contents, Note, and the like) and
glossary.md (the words that language's books use for Singe's terms).

The English stays ASCII.  The translations are UTF-8, with the language's own letters and marks.

## Keeping Them Current

Every change to an English book goes into all four translations in the same change.  Then:

    ruby util/checkTranslations.rb       compares every translation with the English, block by block
    ./build-docs.sh                      builds all five languages

The check finds a section, paragraph, list item, table row, picture, note, or listing the
translation lacks or has extra;  Lua code that differs once comments are taken out;  references
that differ;  and inline code and web addresses that differ (warnings).  It cannot tell a stale
sentence from a current one:  a changed English sentence has to be found and changed in each
translation by hand.

A new section whose id Asciidoctor makes from its title needs that English id written above the
translated heading, or the translated title changes the id and links to it break.  The check names
the id a section should have.

## Rules for Translators

**Translate:**  prose (paragraphs, headings, list items, table cells, notes, block titles such as
.Example), the text of links (`<<id,text>>` and `xref:Book.adoc#id[text]`), a picture's alternative
text (`image::learn/01-hello.png[The finished lesson, 480]`:  the words, not the file or the size),
the labels of the Reference's entries (*Parameters:*, *Returns:*, *Since:*, *See also:*, *Notes:*),
and comments in code listings.  A link whose English text is its target's title gets the
translated title as that language's book has it.

**Never change:**

* anything in backticks, and every listing except its comments;  string literals in code stay as
  they are, because they match the pictures and the shipped lesson scripts;
* ids and anchors (`[#id]`, `[[id]]`), the targets of links, includes, and pictures;
* attribute lines (`:name: value`), block attribute lines (`[source,lua]`, `[cols=...]`), table cell
  specifiers (`a|`, `2+|`), and the admonition keywords (`NOTE:`, `TIP:`, `IMPORTANT:`, `WARNING:`,
  `CAUTION:`), which are syntax:  locale.adoc translates the captions they print;
* `kbd:[...]` and `menu:...[...]` macros and web addresses;
* file names, paths, command line options, settings, function and constant names, and anything
  Singe prints or shows:  its menus and messages are in English, so the books quote them in English.

**Keep the shape:**  the same paragraphs (never merge or split one), the same list items, table
rows, and columns, the same notes, and the same number of lines in every listing.  In a listing
that is not Lua (a folder layout, a settings file, a trace), translate only the descriptions and
comments, line for line.  Wrapping inside a paragraph is free.

**Voice:**  the Manual and the lessons are in the author's voice:  short plain sentences, "you",
direct, a little dry humor.  Keep it plain;  do not make it formal or add words.  The Reference is
dense and exact;  keep it dense and exact.  The lessons are for someone who has never programmed:
keep them friendly and simple.

**Addressing the reader:**  French *vous*;  Italian *tu*;  German *du* (lower case);  Spanish the
familiar singular (never *vosotros*, never *usted*).

**Varieties:**  French of France, Italian of Italy, German of Germany (with the sharp s), Spanish of
Spain (*ordenador*, not *computadora*).

**Headings:**  sentence case in French, Italian, and Spanish (a capital on the first word and on
names only);  German capitalises its nouns as usual.  A heading that is a name from the code
(`==== spriteLoad`, `=== controls.cfg`) stays exactly as it is.

**Typography:**

* French:  guillemets with no-break spaces inside;  a no-break space (U+00A0) before ; : ! ? in
  prose, never inside AsciiDoc syntax (`term::`, `NOTE:`, attributes, macros, inline code).  Type
  ordinary spaces and run `python3 util/frenchSpaces.py`, which makes them no-break.
* German:  low-high quotation marks.
* Italian and Spanish:  guillemets with no spaces inside;  Spanish opens questions and exclamations
  with their inverted marks.
* The English's "`curved quotes`" become the language's own marks.
* An apostrophe straight before or after inline code (l'`id`, `id`'s) is AsciiDoc quote syntax and
  stops the code rendering:  write the typographic apostrophe there (U+2019) or reword.  The check counts
  inline code the way Asciidoctor renders it, so a span lost this way shows up as a warning.
* ` -- ` stays as it is (it prints a dash in every language), but only with a space on both sides:
  `--,` or `--.` prints the two hyphens.  Where the language wants a comma after the dash, recast
  the sentence.
* A decimal in running prose takes the language's comma (1,5 seconds);  a number the reader types,
  or one in code or inline code, never does.

**Names:**  Singe, its expansion "SINGE Is Not a Game Emulator" (which may be glossed in
parentheses), Hypseus, Daphne, Lua, SDL, and every other product name stay as they are.  The books
name no games except where the English does, for Singe's own name;  a translation adds none.
Other programs and keys go by the names the reader's own system shows (Notepad is Bloc-notes on a
French Windows, Ctrl is Strg on a German keyboard):  the glossary lists them.

**Terms:**  use the language's glossary.md.  A term the glossary lacks that comes up more than once
gets one rendering, added to the glossary.