Documentation in seven languages (fr, de, es, zh-Hans, ko, ja)

.github/workflows/docs.yml

@@ -96,6 +96,18 @@ jobs:
           go test ./...
           go run . -src ../../slides-src -out ../..
 
+      # The translations pair up with the English pages: every page of
+      # content/en exists in each language of hugo.yaml, and a translation keeps
+      # the code, the shortcodes, the link targets and the headings' anchors the
+      # English page has. A missing page fails here, before the build.
+      - name: Check the translations
+        env:
+          GOWORK: "off"
+        working-directory: tools/i18n
+        run: |
+          go test ./...
+          go run . -root ../..
+
       # Each page's creation (first commit, followed across renames) and its
       # author, for the page history at its foot (params.page.history).
       - name: Page history
@@ -112,6 +124,15 @@ jobs:
           hugo --gc --minify --panicOnWarning --printPathWarnings
           --baseURL "${DOCS_URL}/${{ steps.version.outputs.version }}/"
 
+      # In the built site, each translated page's headings have the ids of the
+      # English page's, so that a link into a page reaches the same place in
+      # every language.
+      - name: Check the translated anchors
+        env:
+          GOWORK: "off"
+        working-directory: tools/i18n
+        run: go run . -root ../.. -built ../../public
+
       # Internal links and anchors, offline, with the site laid out under
       # /docs/<version>/ as it is served.
       - name: Lay out the site for the link check

README.md

@@ -41,6 +41,10 @@ against that release (flags from its `slides -h`).
 | `assets/css/custom.css` | the brand indigo as Hextra's primary colour, with its contrast measured |
 | `themes/hextra` | submodule: tannevaled/hextra at tag v0.16.0 |
 | `branding` | submodule: [go-slides/brand](https://github.com/go-slides/brand) |
+| `content/<lang>/` | the translations (fr, de, es, zh, ko, ja), with the English file names; Chinese is Simplified (`zh-Hans`). Code, flags, directive names and file names stay as in English; each translated heading carries the English heading's `{#anchor}` |
+| `tools/i18n` | a Go program (stdlib only, with tests): the CI fails when a page of `content/en` is missing in a language of `hugo.yaml` (or exists only in a translation), and warns when a translation changes code, shortcodes, link targets or anchors (`-strict` fails on those too); `-fix` adds the anchors, `-built public` compares the built site's heading ids with the English ones |
+| `static/images/flags` | the language flags, lipis/flag-icons (MIT) |
+| `layouts/baseof.html` | Hextra's, with `lang` taken from the language's `locale` (`zh-Hans`) |
 | `tools/gallery` | a Go program (stdlib only, with tests) that renders the gallery: it reads go-slides/slides' `examples/`, renders each deck's first slide with the slides command, and writes `data/gallery.json` and `static/gallery/` (both ignored by git) |
 | `layouts/_shortcodes/gallery.html` | the gallery page's cards, from `data/gallery.json` |
 | `scripts/publish-version.sh` | puts one build into a `gh-pages` checkout and rewrites `versions.json`, `latest` and the root redirect |

assets/css/custom.css

@@ -29,6 +29,27 @@
  * stays on screen at the end of the navbar. */
 .fs-version-select .hextra-nav-menu-items { left: auto !important; right: 0; transform: none !important; }
 
+/* The navbar's language switch: its flag at the size of the other icons. */
+.hextra-language-switcher[data-location="top"] img { width: 18px; height: 13.5px; }
+
+/* Chinese, Japanese and Korean: the system font stack (Hextra's own, which
+ * leaves the choice to the system) with the CJK system fonts named after
+ * system-ui, so that each language's glyph variants are found on macOS, iOS,
+ * Windows, Android and Linux. lang tells the browser which variants of the
+ * Han characters shared by the three languages to draw. */
+html:lang(zh-Hans) {
+  --hx-font-sans: ui-sans-serif, system-ui, "PingFang SC", "Hiragino Sans GB", "Noto Sans CJK SC", "Source Han Sans SC", "Microsoft YaHei", sans-serif, "Apple Color Emoji", "Segoe UI Emoji", "Noto Color Emoji";
+}
+html:lang(ja) {
+  --hx-font-sans: ui-sans-serif, system-ui, "Hiragino Sans", "Hiragino Kaku Gothic ProN", "Yu Gothic", "Noto Sans CJK JP", "Source Han Sans JP", Meiryo, sans-serif, "Apple Color Emoji", "Segoe UI Emoji", "Noto Color Emoji";
+}
+html:lang(ko) {
+  --hx-font-sans: ui-sans-serif, system-ui, "Apple SD Gothic Neo", "Malgun Gothic", "Noto Sans CJK KR", "Source Han Sans KR", sans-serif, "Apple Color Emoji", "Segoe UI Emoji", "Noto Color Emoji";
+}
+/* Long unbroken runs (a heading, a table cell) wrap rather than overflow. */
+html:lang(zh-Hans) .content, html:lang(ja) .content, html:lang(ko) .content { overflow-wrap: break-word; }
+html:lang(ja) .content, html:lang(zh-Hans) .content { line-break: strict; }
+
 /* The gallery (layouts/_shortcodes/gallery.html): a card per deck. */
 .gallery { display: grid; gap: 1.5rem; grid-template-columns: repeat(auto-fill, minmax(min(100%, 22rem), 1fr)); margin-top: 1.5rem; }
 .gallery-card { border: 1px solid #d1d5db; border-radius: 0.75rem; padding: 0.75rem; min-width: 0; }

content/de/_index.md

@@ -0,0 +1,60 @@
+---
+title: "go-slides-Dokumentation"
+linkTitle: "Start"
+type: docs
+cascade:
+  type: docs
+description: "Marp-kompatible Foliensätze in reinem Go (CGO=0), mit Go-Vorlagen zur Interpolation und Folientypen (Kinds)."
+---
+
+**`slides` macht aus einem Marp-Foliensatz eine Präsentation, in reinem Go.** Es liest
+das Markdown, das auch [Marp](https://marp.app) liest – die Direktiven von Marpit, `---` zwischen
+den Folien, `![bg]`-Hintergründe, Sprechernotizen, die Themes `default`, `gaia` und
+`uncover` – und ergänzt zwei Dinge, die Marp nicht kennt:
+
+- **[Go-Vorlagen]({{< relref "templates" >}})** im Foliensatz, die ausgewertet werden,
+  bevor das Markdown geparst wird, sodass ein Foliensatz seine eigenen Folien erzeugen kann;
+- **[Kinds (Folientypen)]({{< relref "kinds" >}})**: Eine Folie gibt an, was sie ist
+  (`title`, `section` …), statt immer wieder zu wiederholen, wie sie aussieht.
+
+{{< callout type="warning" >}}
+**v0.9.0.** Diese Seiten beschreiben
+[go-slides/slides v0.9.0](https://github.com/go-slides/slides/releases/tag/v0.9.0)
+und sind unter `/docs/0.9/` veröffentlicht.
+{{< /callout >}}
+
+## Was es heute kann {#what-it-does-today}
+
+| | |
+| --- | --- |
+| `slides build` (der Standard) | der Foliensatz als eine HTML-Seite: jede Folie ein `<section>` im SVG-Rahmen, der sich dem Fenster anpasst, dazu das CSS des Themes und ein Tastatur-Viewer |
+| `slides build --pdf`, `--images png`, `--image jpeg` | der Foliensatz als PDF (eine Seite pro Folie, mit Gliederung) oder als PNG-/JPEG-Bilder, ohne Browser: [go-webengine](https://github.com/go-webengine) rendert, [go-pdfkit](https://github.com/go-pdfkit) schreibt das PDF – seit v0.4.0 als Vektoren, mit auswählbarem Text: [Vektor-PDF]({{< relref "cli#vector-pdf" >}}) |
+| Mathematik und Code | `$…$` und `$$…$$` setzt go-tex/math, Codeblöcke hebt go-rouge hervor, in HTML, Bildern und PDF: [Mathematik und Code]({{< relref "math-and-code" >}}) |
+| Emoji | `:smile:` und 😄 werden zu eingebetteten Twemoji-Bildern, brauchen also kein Netzwerk und erscheinen in jeder Ausgabe: [Emoji]({{< relref "emoji" >}}) (seit v0.4.0) |
+| `slides build --pptx` | der Foliensatz als PowerPoint-Datei mit Sprechernotizen und den Metadaten des Foliensatzes: in v0.4.0 ein Bild pro Folie wie bei marp-cli; seit v0.5.0 **editierbar** – Textfelder, Formen, Bilder, eingebettete Schriften ([Editierbares PPTX und ODP]({{< relref "cli#editable-pptx-and-odp" >}})) |
+| `slides build --odp` | dasselbe als OpenDocument-Präsentation (`.odp`) |
+| einpassende Überschriften | `# <!-- fit --> Title` füllt die Folienbreite in einer Zeile, auf der Seite und in jedem Export |
+| `slides expand` | der Foliensatz als reines Marp-Markdown: Vorlagen ausgewertet, Kinds durch die Spot-Direktiven ersetzt, für die sie stehen |
+| `slides notes` | die Sprechernotizen |
+| `slides kinds`, `slides themes` | was ein Foliensatz benennen kann |
+| `slides.yaml` | gemeinsame Kinds, Themes, Daten, HTML-Richtlinie und Sprache für einen Ordner voller Foliensätze |
+| HCL | `---hcl`-Front-Matter, `slides.hcl`, Kinds- und Datendateien in HCL2, mit Ausdrücken und Funktionen: [HCL]({{< relref "hcl" >}}) |
+
+## Geplant {#planned}
+
+Noch nicht gebaut, und hier aufgeführt, damit niemand raten muss: Formeln als Vektoren im
+PDF (dort sind sie Bitmaps). Der Unterschied zu
+marp-cli liegt im Weg: Es rendert Bilder und PDF, indem es einen Headless-Chrome steuert;
+hier erledigen das Go-Bibliotheken.
+
+## Seiten {#pages}
+
+- [Erste Schritte]({{< relref "getting-started" >}})
+- [Galerie]({{< relref "gallery" >}}): zwölf Beispiel-Foliensätze, zum Öffnen im Playground
+- [Marp-Kompatibilität]({{< relref "marp" >}})
+- [Vorlagen]({{< relref "templates" >}})
+- [Kinds]({{< relref "kinds" >}})
+- [HCL]({{< relref "hcl" >}})
+- [Mathematik und Code]({{< relref "math-and-code" >}})
+- [Emoji]({{< relref "emoji" >}})
+- [Kommandozeile]({{< relref "cli" >}})