docs: document the interface language, theme settings, slide links and titles

src/content/built-in/cli.md

@@ -26,6 +26,7 @@ Starts the dev server. This is the default command.
 | `--log error\|warn\|info\|silent` | How much of the child programs' output to show. Default `info`. `error` and `silent` hide it. |
 | `--force`, `-f` | Clear the build cache. |
 | `--theme`, `-t` | A theme name or path, instead of the headmatter's. |
+| `--lang <tag>` | Use this language (`tr`, `pt-BR`) instead of the headmatter's `lang`: the interface, the locale of dates and numbers, and `<html lang>`. See [Interface language](../features/interface-language.md). |
 
 `--tunnel` and `--base` are refused with a message. The dev server always runs at `/`.
 
@@ -45,6 +46,7 @@ Makes a static site. See [Hosting](../guide/hosting.md).
 | `--allow-local` | Let the page Chromium renders reach loopback and private addresses. They are blocked otherwise. |
 | `--timeout` | Timeout in milliseconds for each page Chromium renders. |
 | `--theme`, `-t` | A theme name or path. |
+| `--lang <tag>` | Use this language instead of the headmatter's `lang`, for one deck in several languages: `slide-ng build slides.tr.md --out dist/tr`. |
 
 ## export
 
@@ -71,6 +73,7 @@ Makes a PDF, PNG, PPTX or Markdown file. See [Export](../guide/export.md).
 | `--url <address>` | Export a running server, for example the dev server. |
 | `--base` | The base path the deck is served under, for `--dist`. |
 | `--theme`, `-t` | A theme name or path. |
+| `--lang <tag>` | Use this language instead of the headmatter's `lang`. |
 
 `export` takes one entry file per run. A `--range` that picks no slide fails before the deck is built.
 
@@ -124,6 +127,7 @@ Makes a new deck folder. `--force`, `-f` adds the files that are missing to a fo
 | --- | --- |
 | `CHROME_PATH` | The Chromium that export, `--download`, `pwa` icons and `ogImage: auto` use. |
 | `SLIDE_NG_THEME` | A theme name or path that overrides the headmatter. `--theme` sets it. |
+| `SLIDE_NG_LANG` | The same as `--lang`. |
 | `SLIDE_NG_NO_SANDBOX` | `1` is the same as `--no-sandbox`. |
 | `SLIDE_NG_PASSWORD` | The password for `dev --remote`. It keeps the password out of the shell history. |
 | `SLIDES_FILE` | The entry file, when no argument names one. |

src/content/built-in/components.md

@@ -14,6 +14,7 @@ These tags work in every slide. The generator imports a component only into the
 | `<slide-ng-toc />` | Table of contents from slide titles and levels. Options: `columns`, `listClass`, `listStyle`, `start`, `minDepth`, `maxDepth`, `mode`. See [Table of contents](../features/table-of-contents.md). |
 | `<slide-ng-current-no />` | The number of the slide it is on. |
 | `<slide-ng-total />` | The number of slides. |
+| `<slide-ng-title-renderer />` | The title of the slide it is on, as HTML: its inline markdown and `$math$` are drawn. `no="3"` shows the title of slide 3. Raw HTML in a title is shown as text. Slidev's `TitleRenderer`. |
 | `<slide-ng-link to="3">text</slide-ng-link>` | A link to slide 3, or to a `routeAlias`. It has the prefix because `link` is a built-in HTML tag. The link has the slide's real address, so Ctrl or Cmd + click opens it in a new tab. `title="Details"` is the text when the tag has none. |
 | `<slide-ng-light-or-dark>` | Shows `<div dark>...</div>` in dark mode and `<div light>...</div>` in light mode. |
 | `<slide-ng-render-when context="slide">` | Content only where the slide is drawn: `slide`, `presenter`, `print`, `overview`, or `main` (slide or presenter). `[context]="['slide','overview']"` takes several. Content marked `<div fallback>` shows everywhere else. |
@@ -42,7 +43,7 @@ These tags work in every slide. The generator imports a component only into the
 
 | Tag | What it does |
 | --- | --- |
-| `<slide-ng-youtube id="luoMHjh-XcQ" width="560" height="315" />` | An embedded YouTube video. `id` is the video id. There are no start time or playlist options. |
+| `<slide-ng-youtube id="luoMHjh-XcQ?start=60" width="560" height="315" />` | An embedded YouTube video. `id` is the video id, optionally followed by YouTube's embed options, as in Slidev: `?start=60&end=90`, `list`, `loop`, `autoplay`, `mute` and the other documented ones. Other options are dropped. `start` (seconds) and `list` (a playlist id) can also be attributes, and they win over the same option in `id`. |
 | `<slide-ng-video autoplay="true" autoreset="click" controls poster="...">` | A video that plays when its slide, or its `slide-ng-click`, comes. `autoplay="once"` plays once. `timestamp` starts at a second. Put `<source>` tags inside. |
 | `<slide-ng-tweet id="20" scale="0.8" conversation="none" cards="hidden" />` | An embedded tweet. Loads Twitter's script, so it needs the network. |
 | `<slide-ng-blue-sky uri="at://did:.../app.bsky.feed.post/..." scale="0.8" />` | An embedded Bluesky post, needs the network. `uri` can also be the post's web address. |
@@ -63,4 +64,4 @@ These tags work in every slide. The generator imports a component only into the
 
 ## Not there
 
-Slidev's `PoweredBySlidev` badge and `TitleRenderer` are not available. Slide titles are plain text, except that `$math$` in a title is drawn in `<slide-ng-toc>`. Your own components work like these, see [Layouts and components](../customize/layouts-components.md).
+Slidev's `PoweredBySlidev` badge is not available. Your own components work like these, see [Layouts and components](../customize/layouts-components.md).

src/content/built-in/headmatter.md

@@ -42,6 +42,7 @@ The first block of YAML in `slides.md` is the headmatter. It describes the deck.
 | `zoom` | Scale every slide. |
 | `routerMode` | `history` (default) or `hash`. |
 | `fonts` | Web fonts. See [Fonts](../features/fonts.md). |
+| `themeConfig` | Settings for the theme, such as `themeConfig: { primary: '#5d8392' }`. Each text or number key becomes the CSS variable `--slidev-theme-<key>`. See [Themes and addons](../customize/themes.md#theme-settings). |
 | `customElements` | Web component tags the slides may use, such as `[model-viewer, sl-*]`. A name ending in `*` is a prefix, and `true` allows any tag with a dash. See [Layouts and components](../customize/layouts-components.md#web-components). |
 
 ### Code and diagrams
@@ -71,7 +72,8 @@ The first block of YAML in `slides.md` is the headmatter. It describes the deck.
 
 | Key | What it does |
 | --- | --- |
-| `titleTemplate`, `author`, `keywords`, `favicon`, `lang`, `htmlAttrs`, `seoMeta` | The page's `<head>`. See [Page head and SEO](../features/seo-meta.md). |
+| `titleTemplate`, `author`, `keywords`, `favicon`, `htmlAttrs`, `seoMeta` | The page's `<head>`. See [Page head and SEO](../features/seo-meta.md). |
+| `lang`, `uiLang` | `lang` is `<html lang>`, the interface language and the locale of the `date`, `number` and `currency` pipes. `ar`, `he`, `fa` and `ur` mirror the page. `uiLang` changes the interface language only. See [Interface language](../features/interface-language.md). |
 | `download` | A PDF button: `true`, a file name or an address. With `true`, `slide-ng build` makes the PDF. Without a working Chromium it warns and the button stays disabled. |
 | `exportFilename` | The name of exported files, without the extension. |
 | `export` | Defaults for `slide-ng export`. See [Export](../guide/export.md). |
@@ -81,4 +83,4 @@ The first block of YAML in `slides.md` is the headmatter. It describes the deck.
 
 ## Not read
 
-These Slidev keys are accepted in the file but have no effect: `selectable`, `themeConfig`, `preload`, `clickAnimation`, `overviewSnapshots`, `browserExporter`, `notesAutoRuby`, `monacoTypesSource`, and `colorSchema: all`. `mdc: true` and `comark: true` have no effect, and the generator warns that MDC syntax stays text. `highlighter: prism` warns too, because code is always highlighted with Shiki. The `monaco` and `twoslash` switches of Slidev are not read either: a `{monaco}` or `twoslash` code fence is what turns them on. A key a theme brings through `theme.json` is merged under the deck's headmatter, except a fixed `colorSchema`, see [Themes and addons](../customize/themes.md).
+These Slidev keys are accepted in the file but have no effect: `selectable`, `preload`, `clickAnimation`, `overviewSnapshots`, `browserExporter`, `notesAutoRuby`, `monacoTypesSource`, and `colorSchema: all`. `mdc: true` and `comark: true` have no effect, and the generator warns that MDC syntax stays text. `highlighter: prism` warns too, because code is always highlighted with Shiki. The `monaco` and `twoslash` switches of Slidev are not read either: a `{monaco}` or `twoslash` code fence is what turns them on. A key a theme brings through `theme.json` is merged under the deck's headmatter, except a fixed `colorSchema`, see [Themes and addons](../customize/themes.md).

src/content/customize/directory-structure.md

@@ -16,6 +16,7 @@ my-deck/
   styles/index.css    CSS added after the app's styles
   public/             files served from the site root (/logo.png)
   setup/              setup hooks: shiki.ts, katex.ts, mermaid.ts, shortcuts.ts, ...
+  locales/            translations of the interface: tr.json, de.json, ...
   uno.config.mjs      UnoCSS settings
   theme.json          inputs and slots of your own layouts
   snippets/           anything you import with <<<
@@ -42,6 +43,7 @@ So a deck can put a `layouts/cover.ts` next to `slides.md` and it beats the them
 | `styles/index.css` | CSS, added after the app's styles. |
 | `public/` | Files served from the site root. The later root wins on the same name. |
 | `setup/*.ts` | [Setup hooks](./setup-hooks.md). |
+| `locales/<lang>.json` | Translations of the interface, flat `"key": "text"` pairs. Merged key by key, the later root wins. See [Interface language](../features/interface-language.md). |
 | `uno.config.mjs` | UnoCSS settings, default export. `presets`, `rules`, `safelist` and `variants` are added to the app's. `shortcuts` and `theme` are merged key by key. |
 | `theme.json` | Name, default headmatter and layout inputs and slots. A deck's own folder can have one too, for its own layouts. See [Writing a theme](./writing-a-theme.md). |
 

src/content/customize/setup-hooks.md

@@ -135,7 +135,7 @@ See [Shortcuts](../built-in/shortcuts.md). The roots are chained: each gets the
 
 ## Context menu
 
-`setup/context-menu.ts` gets the entries of the right-click menu and returns the list to show. An entry is `{ icon, label, run, disabled? }`, and `icon` is an icon class such as `i-carbon:star`. The roots are chained.
+`setup/context-menu.ts` gets the entries of the right-click menu and returns the list to show. An entry is `{ icon, label, run, disabled? }`, and `icon` is an icon class such as `i-carbon:star`. The roots are chained. The built-in labels are in the deck's [interface language](../features/interface-language.md), so pick an entry by its `icon`, not its label.
 
 ```ts
 // setup/context-menu.ts

src/content/customize/themes.md

@@ -48,6 +48,35 @@ A theme can bring layouts, components, layers, CSS, public files, UnoCSS setting
 
 The one exception is `colorSchema`. A theme that sets `light` or `dark` has colours for that mode only, so every deck that uses it keeps that mode, as in Slidev. The toggle is gone, and when the deck's headmatter asks for another mode the generator says that it is not used. Of the official themes, `bricks` is light only and `shibainu` dark only.
 
+## Theme settings
+
+`themeConfig` holds the values a theme offers to change, as in Slidev. Each key with a text or number value becomes the CSS variable `--slidev-theme-<key>` on `<body>`, with the key as written: `primary` is `--slidev-theme-primary`, `accentDark` is `--slidev-theme-accentDark`. It is there in the page, the presenter, the PDF and offline builds.
+
+```md
+---
+themeConfig:
+  primary: '#5d8392'
+---
+```
+
+`primary` recolours the built-in accent: `text-primary`, `bg-primary`, `border-primary`, the progress bar and the controls. Other keys do what the theme makes of them.
+
+- The theme's `theme.json` can give defaults. The deck's keys win, key by key, and so do an addon's.
+- A key must be letters, digits, `-` and `_`. A value that could leave the CSS declaration (`;`, `{`, `}`, `<`, `>`, `\`, a comment, a line break, quotes or brackets that do not close) is skipped with a warning.
+- There is one value for both colour modes, as in Slidev.
+- A slide reads the whole map as `themeConfig`, for example `{{ themeConfig['primary'] }}`. The brackets are needed because the map has no fixed keys. Lists and objects are kept there, but they are not CSS variables.
+- A theme's component reads it with `inject(THEME_CONFIG)` from `slide-ng/lib/theme-config`. See [Writing a theme](./writing-a-theme.md#5-default-settings).
+
+## Translating the interface
+
+A theme or an addon can translate slide.ng's own interface (the bar, the menus, the presenter) with a `locales/` folder. `locales/tr.json`, or `pt.json` and `pt-BR.json`, holds flat `"key": "text"` pairs with their `{name}` placeholders kept:
+
+```json
+{ "nav.next": "Sonraki slayta git", "presenter.noNotes": "{no}. slayt için not yok." }
+```
+
+The deck's `lang` or `uiLang` picks the file. The built-in translations come first, then the theme, the addons and the deck, key by key, so a deck can change one text of its theme. A theme's own components can show the same texts with the `t` pipe: import `T` from `slide-ng/i18n/t`, then write `{{ 'nav.next' | t }}`. See [Interface language](../features/interface-language.md).
+
 ## Eject a theme
 
 ```sh
@@ -63,7 +92,6 @@ The built-in styles still load before the ejected `styles/index.css`. Your copy
 - There is no versioning or compatibility check between a theme and the app.
 - A layout's inputs are not read from the component, because Angular decorators are not parsed. They come from the built-in layout or from `theme.json`.
 - Class names in a theme are found by UnoCSS in `.ts` files of the roots and in the deck's markdown, not in CSS files.
-- `themeConfig` is not read.
 - `@apply` in a theme's CSS does nothing, because there is no UnoCSS directive transformer. The generator warns. Write the CSS out, or put the classes on the elements.
 - A theme package whose `files` leaves its folders out installs empty. The generator warns, instead of failing later with "is not a known element".
 

src/content/customize/writing-a-theme.md

@@ -18,6 +18,7 @@ my-theme/
   layers/          optional: global-top.ts, global-bottom.ts, slide-top.ts, slide-bottom.ts
   setup/           optional: setup hooks
   public/          optional: pictures and fonts, served from /
+  locales/         optional: translations of the interface, tr.json, de.json, ...
   uno.config.mjs   optional: UnoCSS shortcuts and rules
 ```
 
@@ -86,9 +87,23 @@ Dark mode is the class `dark` on `<html>`: write `html.dark .my-quote { ... }` f
 - A `colorSchema` of `light` or `dark` says the theme has colours for that mode only: every deck that uses it keeps that mode, and the generator warns when a deck asks for another. Leave it out when the theme styles both.
 - `layouts.<name>`: `props` are the frontmatter keys that become inputs, `slots` are the names accepted after `::name::`, and `classProp: true` sends the slide's `class` to the input `contentClass` instead of the tag.
 
+Settings a deck may change, such as the accent colour, go in `themeConfig`, as in Slidev. Each one is the CSS variable `--slidev-theme-<key>` on `<body>`, and the deck's `themeConfig: { accent: '#22c55e' }` replaces your default:
+
+```json
+{ "headmatter": { "themeConfig": { "accent": "#f59e0b" } } }
+```
+
+```css
+.my-quote {
+  border-left: 4px solid var(--slidev-theme-accent);
+}
+```
+
+The variables are written after the roots' style sheets, so they win over a value you set on `:root` or `html.dark`. Use them in rules on the elements, or alias them on `body` or below: an alias on `:root` is worked out before the variable exists there. `primary` is the colour of the built-in accent (`text-primary`, the progress bar). In a component, `inject(THEME_CONFIG)` from `slide-ng/lib/theme-config` gives the whole map, lists and objects too. There is one value for both colour modes, so a theme that wants another dark colour can offer a second key, such as `primaryDark`, and use it under `html.dark`. The rules for values are in [Themes and addons](./themes.md#theme-settings).
+
 Keys other than `name`, `headmatter` and `layouts` are not read, and the generator says so: settings such as `colorSchema` and `fonts` go under `headmatter`. A value of the wrong type is reported and ignored. A deck's own folder can have a `theme.json` too, to describe the inputs and slots of its own layouts.
 
-Pictures go in `public/`.
+Pictures go in `public/`. Translations of slide.ng's interface go in `locales/<lang>.json`, see [Themes and addons](./themes.md#translating-the-interface).
 
 ## A footer or page number
 
@@ -114,7 +129,7 @@ A theme is a folder, so publish it as an npm package with these folders at the t
   "version": "1.0.0",
   "license": "MIT",
   "keywords": ["slide-ng-theme", "slide-ng"],
-  "files": ["layouts", "components", "layers", "styles", "public", "setup", "theme.json", "uno.config.mjs"],
+  "files": ["layouts", "components", "layers", "styles", "public", "setup", "locales", "theme.json", "uno.config.mjs"],
   "peerDependencies": { "@slide-ng/core": "*" }
 }
 ```