You can not select more than 25 topics
Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
39 lines
2.0 KiB
39 lines
2.0 KiB
# Translations
|
|
|
|
## Current layout
|
|
|
|
**MkDocs** pages exist in parallel trees:
|
|
|
|
| Locale | Path | Build |
|
|
|--------|------|-------|
|
|
| English | **`docs/en/`** | `mkdocs.yml` → **`site/en/`** |
|
|
| Spanish | **`docs/es/`** | **`mkdocs.es.yml`** → **`site/es/`** |
|
|
|
|
- **`docs/en/server/`** — ADN DMR Peer Server (user guide, protocols, development, contributing).
|
|
- **`docs/en/monitor/`** — ADN Monitor (dashboard, `adn-monitor.yaml`, self-service).
|
|
|
|
Spanish mirrors the same relative paths under **`docs/es/`**.
|
|
|
|
`mkdocs.yml` sets **`docs_dir: docs/en`** and **`theme.language: en`**. **`mkdocs.es.yml`** sets **`docs_dir: docs/es`** and **`theme.language: es`**.
|
|
|
|
Build **both** (`mkdocs build` and `mkdocs build -f mkdocs.es.yml`). The outputs land in **`site/en/`** and **`site/es/`**. Publish the combined **`site/`** directory as your HTTP server layout requires.
|
|
|
|
For a quick local check: `cd site && python -m http.server` then open **`/en/`** and **`/es/`** (paths at the server root). On production, the site is usually mounted under **`/docs/`**; the language switcher and **`docs/site-root-index.html`** use **`/docs/en/`** and **`/docs/es/`**. Optional: use **`mkdocs-static-i18n`** later for a single build with page-level language pairs.
|
|
|
|
## Adding or updating a locale
|
|
|
|
1. Keep **navigation structure** aligned across locales (same relative paths: `server/user-guide/introduction.md`, etc.).
|
|
2. Headings that are cross-linked use **`attr_list`** explicit anchors `{#id}` where slugs must stay stable — see Spanish pages for examples.
|
|
3. When adding a third locale, add another MkDocs config and output directory following the same pattern.
|
|
|
|
## Writing for translators
|
|
|
|
- Use **short, clear sentences**.
|
|
- Avoid idioms and culture-specific jokes.
|
|
- Keep **terminology** consistent (OpenBridge, BCSQ, TG, `BRIDGES`).
|
|
- Put **code identifiers** and **YAML keys** in backticks.
|
|
|
|
## Not translated by default
|
|
|
|
- The **repository root** `README.md` may stay English-only or link to the published docs site.
|