Vateron-Media/XC_VM
1
0
Fork 0
mirror of https://github.com/Vateron-Media/XC_VM.git synced 2026-10-31 11:03:22 +01:00
Code Issues 1 Packages Projects Releases 6 Wiki Activity

[PR #159] [MERGED] docs: migrate to MkDocs Material with auto-translated ru (English is the single source) #83

New Issue
Closed
opened 2026-08-21 20:02:38 +02:00 by thegame_1980 · 0 comments
thegame_1980 commented 2026-08-21 20:02:38 +02:00
Owner
Copy Link
Copy Source

📋 Pull Request Information

Original PR: https://github.com/Vateron-Media/XC_VM/pull/159
Author: @Divarion-D
Created: 8/21/2026
Status: ✅ Merged
Merged: 8/21/2026
Merged by: @Divarion-D

Base: main ← Head: feature/docs-autotranslate

📝 Commits (5)

  • dcd1d8c docs: migrate to MkDocs Material with auto-translated ru from English
  • c55238f docs(dev): document daemon delivery, Redis idle-resilience, cold-cache safety
  • bdbcde9 docs: commit generated ru, translate locally before release (not in CI)
  • dbf535b docs(translate): robust {N} sentinels + possessive handling; regenerate ru
  • b23adc2 docs: translate ru navigation labels (nav_translations)

📊 Changes

61 files changed (+4451 additions, -4069 deletions)

View changed files

📝 .github/workflows/pages.yml (+19 -6)
📝 .gitignore (+6 -1)
📝 Makefile (+41 -0)
➖ docs/.nojekyll (+0 -0)
➖ docs/_navbar.md (+0 -5)
📝 docs/adr/plan-ffmpeg-per-distro-distribution.ru.md (+0 -0)
📝 docs/adr/plan-ministra-module-extraction.ru.md (+0 -0)
➖ docs/en/_sidebar.md (+0 -55)
📝 docs/en/administration/server-diagnostics.md (+1 -1)
📝 docs/en/administration/server-update.md (+2 -2)
📝 docs/en/administration/update-system.md (+2 -2)
📝 docs/en/api/swagger.md (+8 -8)
📝 docs/en/builds/updates_checklist.md (+29 -0)
📝 docs/en/development/caching-and-redis.md (+40 -0)
📝 docs/en/development/streaming-subsystem.md (+40 -5)
📝 docs/en/guides/cli-tools.md (+2 -2)
📝 docs/en/info/faq.md (+2 -2)
➖ docs/index.html (+0 -154)
➕ docs/requirements.txt (+6 -0)
📝 docs/ru/README.md (+31 -31)

...and 41 more files

📄 Description

Summary

Replaces the hand-maintained Docsify site (two parallel docs/en + docs/ru trees that had already drifted) with a MkDocs Material build where English is the single source of truth and Russian is generated from it. Adds a free, key-less translation pipeline and a two-tab User/Developer information architecture.

What changed

Engine & structure

  • MkDocs Material (mkdocs.yml), site_url set for the /XC_VM/ GitHub Pages subpath.
  • Two nav tabs — User Guide (administration, API/Swagger, UI translations, diagnostics, info/FAQ) vs Developer Guide (architecture, workflow, security, integrations, build). The split is nav-only — files are not moved, so URLs and cross-links stay stable.
  • i18n via mkdocs-static-i18n (folder mode): English at root, Russian under /ru/, with a language switcher. nav_translations localizes the sidebar/tab labels too. mkdocs build --strict validates every link/anchor.
  • Removed Docsify control files (index.html, _navbar.md, _sidebar.md, .nojekyll) and de-Docsify-ed body links (en-us/ aliases → relative, swagger _media paths).

Translation pipeline (tools/docs/translate.py)

  • Engine-agnostic via DOCS_TRANSLATE_PROVIDER: translators (free web engines, no API key — default), anthropic, deepl, noop.
  • Markdown-safe: code, URLs, HTML tags and glossary terms (XC_VM, FFmpeg, HLS, KeyDB, …) are masked behind {N} sentinels; a trailing possessive 's is folded into the masked span; a validate-and-retry loop guarantees no broken sentinel ever reaches the output (falls back to English for a line rather than emit garbage).
  • Per-file sha256 cache — only changed English files re-translate.

Where translation runs

  • Translation is local, before a release (make docs-translate) — deliberately not in CI (it is slow). docs/ru is a committed, generated tree; pages.yml only builds it.
  • New Makefile targets (docs-venv / docs-translate / docs-build / docs-serve), split requirements (docs/requirements.txt = build; tools/docs/requirements.txt = translation), and a "Regenerate translated documentation" step in the release checklist.

Content enrichment (English source)

  • development/streaming-subsystem.md: daemon-only client delivery via xc_fanout (X-Accel handoff, control-socket off-air/telemetry, fanout_sync reconciliation) + the "Send Message" drawtext overlay.
  • development/caching-and-redis.md: how long-lived daemon Redis connections survive an idle timeout close, and cold-cache fail-closed defaults.

Rule going forward

Edit only docs/en. docs/ru is generated — never hand-edit it; regenerate with make docs-translate before a release and commit it.

Validation

  • mkdocs build --strict clean for both languages (0 broken links/anchors).
  • Full ru regeneration: 37/37 files translated, 0 broken sentinels, 0 fallbacks.
  • ru nav labels localized; en unchanged.

Free MT (yandex) quality caveat: wording is "good enough", not professional — switch DOCS_TRANSLATE_PROVIDER=anthropic (needs a key) for higher fidelity.

🤖 Generated with Claude Code

Summary by Sourcery

Migrate the documentation site from Docsify to MkDocs Material with English as the canonical source and locally generated Russian translations.

New Features:

  • Add a MkDocs Material documentation site with user and developer guide navigation, localized Russian pages, and language switching.
  • Add a local, configurable documentation translation pipeline with glossary protection, incremental caching, multiple providers, and generated Russian output.
  • Document daemon-based live streaming delivery, targeted message overlays, Redis reconnect handling, and cold-cache fail-closed behavior.

Bug Fixes:

  • Correct documentation links and asset paths for the MkDocs site and remove obsolete Docsify-specific references.

Enhancements:

  • Make English documentation the single editable source and treat the committed Russian tree as generated release output.
  • Add strict documentation builds and local Makefile workflows for previewing, translating, and validating documentation.

Build:

  • Replace the Docsify publishing setup with MkDocs Material configuration, dedicated documentation dependencies, and a strict static site build.

CI:

  • Update GitHub Pages workflow to install the MkDocs toolchain, run strict builds, and publish the generated site artifact without translating in CI.

Documentation:

  • Reorganize documentation into User Guide and Developer Guide navigation tabs while retaining existing file locations.
  • Expand release documentation with translated-documentation regeneration and review steps.

Tests:

  • Validate both language builds with strict link and anchor checking.

Chores:

  • Remove obsolete Docsify control files and split documentation build and translation requirements.

🔄 This issue represents a GitHub Pull Request. It cannot be merged through Gitea due to API limitations.

## 📋 Pull Request Information **Original PR:** https://github.com/Vateron-Media/XC_VM/pull/159 **Author:** [@Divarion-D](https://github.com/Divarion-D) **Created:** 8/21/2026 **Status:** ✅ Merged **Merged:** 8/21/2026 **Merged by:** [@Divarion-D](https://github.com/Divarion-D) **Base:** `main` ← **Head:** `feature/docs-autotranslate` --- ### 📝 Commits (5) - [`dcd1d8c`](https://github.com/Vateron-Media/XC_VM/commit/dcd1d8c860aa19966e94bf7d80f5fb623bf03d8f) docs: migrate to MkDocs Material with auto-translated ru from English - [`c55238f`](https://github.com/Vateron-Media/XC_VM/commit/c55238f85bae73df74f01fe3c39076a21f30501c) docs(dev): document daemon delivery, Redis idle-resilience, cold-cache safety - [`bdbcde9`](https://github.com/Vateron-Media/XC_VM/commit/bdbcde97c72fe0552cb4d59dcebb9abb3786a03d) docs: commit generated ru, translate locally before release (not in CI) - [`dbf535b`](https://github.com/Vateron-Media/XC_VM/commit/dbf535bcc53b90eaa3b6093ca0b2baf5b93ebb5f) docs(translate): robust {N} sentinels + possessive handling; regenerate ru - [`b23adc2`](https://github.com/Vateron-Media/XC_VM/commit/b23adc2593ecef9301cdb1e1e0e20112d820bcd3) docs: translate ru navigation labels (nav_translations) ### 📊 Changes **61 files changed** (+4451 additions, -4069 deletions) <details> <summary>View changed files</summary> 📝 `.github/workflows/pages.yml` (+19 -6) 📝 `.gitignore` (+6 -1) 📝 `Makefile` (+41 -0) ➖ `docs/.nojekyll` (+0 -0) ➖ `docs/_navbar.md` (+0 -5) 📝 `docs/adr/plan-ffmpeg-per-distro-distribution.ru.md` (+0 -0) 📝 `docs/adr/plan-ministra-module-extraction.ru.md` (+0 -0) ➖ `docs/en/_sidebar.md` (+0 -55) 📝 `docs/en/administration/server-diagnostics.md` (+1 -1) 📝 `docs/en/administration/server-update.md` (+2 -2) 📝 `docs/en/administration/update-system.md` (+2 -2) 📝 `docs/en/api/swagger.md` (+8 -8) 📝 `docs/en/builds/updates_checklist.md` (+29 -0) 📝 `docs/en/development/caching-and-redis.md` (+40 -0) 📝 `docs/en/development/streaming-subsystem.md` (+40 -5) 📝 `docs/en/guides/cli-tools.md` (+2 -2) 📝 `docs/en/info/faq.md` (+2 -2) ➖ `docs/index.html` (+0 -154) ➕ `docs/requirements.txt` (+6 -0) 📝 `docs/ru/README.md` (+31 -31) _...and 41 more files_ </details> ### 📄 Description ## Summary Replaces the hand-maintained **Docsify** site (two parallel `docs/en` + `docs/ru` trees that had already drifted) with a **MkDocs Material** build where **English is the single source of truth** and Russian is generated from it. Adds a free, key-less translation pipeline and a two-tab User/Developer information architecture. ## What changed **Engine & structure** - **MkDocs Material** (`mkdocs.yml`), `site_url` set for the `/XC_VM/` GitHub Pages subpath. - Two nav tabs — **User Guide** (administration, API/Swagger, UI translations, diagnostics, info/FAQ) vs **Developer Guide** (architecture, workflow, security, integrations, build). The split is **nav-only** — files are not moved, so URLs and cross-links stay stable. - **i18n** via `mkdocs-static-i18n` (folder mode): English at root, Russian under `/ru/`, with a language switcher. `nav_translations` localizes the sidebar/tab labels too. `mkdocs build --strict` validates every link/anchor. - Removed Docsify control files (`index.html`, `_navbar.md`, `_sidebar.md`, `.nojekyll`) and de-Docsify-ed body links (`en-us/` aliases → relative, swagger `_media` paths). **Translation pipeline (`tools/docs/translate.py`)** - Engine-agnostic via `DOCS_TRANSLATE_PROVIDER`: **`translators`** (free web engines, no API key — default), `anthropic`, `deepl`, `noop`. - **Markdown-safe**: code, URLs, HTML tags and glossary terms (`XC_VM`, `FFmpeg`, `HLS`, `KeyDB`, …) are masked behind `{N}` sentinels; a trailing possessive `'s` is folded into the masked span; a validate-and-retry loop guarantees no broken sentinel ever reaches the output (falls back to English for a line rather than emit garbage). - **Per-file sha256 cache** — only changed English files re-translate. **Where translation runs** - Translation is **local, before a release** (`make docs-translate`) — deliberately **not** in CI (it is slow). `docs/ru` is a committed, generated tree; `pages.yml` only builds it. - New Makefile targets (`docs-venv` / `docs-translate` / `docs-build` / `docs-serve`), split requirements (`docs/requirements.txt` = build; `tools/docs/requirements.txt` = translation), and a "Regenerate translated documentation" step in the release checklist. **Content enrichment** (English source) - `development/streaming-subsystem.md`: daemon-only client delivery via `xc_fanout` (X-Accel handoff, control-socket off-air/telemetry, `fanout_sync` reconciliation) + the "Send Message" `drawtext` overlay. - `development/caching-and-redis.md`: how long-lived daemon Redis connections survive an idle `timeout` close, and cold-cache fail-closed defaults. ## Rule going forward **Edit only `docs/en`.** `docs/ru` is generated — never hand-edit it; regenerate with `make docs-translate` before a release and commit it. ## Validation - `mkdocs build --strict` clean for both languages (0 broken links/anchors). - Full ru regeneration: 37/37 files translated, 0 broken sentinels, 0 fallbacks. - ru nav labels localized; en unchanged. > Free MT (yandex) quality caveat: wording is "good enough", not professional — switch `DOCS_TRANSLATE_PROVIDER=anthropic` (needs a key) for higher fidelity. 🤖 Generated with [Claude Code](https://claude.com/claude-code) ## Summary by Sourcery Migrate the documentation site from Docsify to MkDocs Material with English as the canonical source and locally generated Russian translations. New Features: - Add a MkDocs Material documentation site with user and developer guide navigation, localized Russian pages, and language switching. - Add a local, configurable documentation translation pipeline with glossary protection, incremental caching, multiple providers, and generated Russian output. - Document daemon-based live streaming delivery, targeted message overlays, Redis reconnect handling, and cold-cache fail-closed behavior. Bug Fixes: - Correct documentation links and asset paths for the MkDocs site and remove obsolete Docsify-specific references. Enhancements: - Make English documentation the single editable source and treat the committed Russian tree as generated release output. - Add strict documentation builds and local Makefile workflows for previewing, translating, and validating documentation. Build: - Replace the Docsify publishing setup with MkDocs Material configuration, dedicated documentation dependencies, and a strict static site build. CI: - Update GitHub Pages workflow to install the MkDocs toolchain, run strict builds, and publish the generated site artifact without translating in CI. Documentation: - Reorganize documentation into User Guide and Developer Guide navigation tabs while retaining existing file locations. - Expand release documentation with translated-documentation regeneration and review steps. Tests: - Validate both language builds with strict link and anchor checking. Chores: - Remove obsolete Docsify control files and split documentation build and translation requirements. --- <sub>🔄 This issue represents a GitHub Pull Request. It cannot be merged through Gitea due to API limitations.</sub>
thegame_1980 added the pull-request label 2026-08-21 20:02:38 +02:00
Sign in to join this conversation.
No Branch/Tag Specified
Branches Tags
Labels
Clear labels
Post-release verification
It is necessary to check whether the problem remains after the update
 Review & Deploy
Board status (auto-synced from Projects v2)
 awaiting triage
Not yet reviewed/prioritized
 bug
Something isn't working
 composer
Composer bump: re-commit a production-only vendor (composer install --no-dev) after merging
 dependencies
Dependency update (Dependabot)
 documentation
Improvements or additions to documentation
 done
Successfully completed and ready for closure.
 duplicate
This issue or pull request already exists
 enhancement
New feature or request
 github-actions
GitHub Actions version bump
 good first issue
Good for newcomers
 help wanted
Extra attention is needed
 in progress
Actively being worked on right now.
 incident
Production incident (outage/degradation)
 invalid
This doesn't seem right
 needs info
More information is needed before work can start.
 on hold
Work is paused, pending external action or decision.
 planned
Approved and scheduled for future work.
 pull-request
Mirrored from GitHub Pull Request
 question
Further information is requested
 rejected
Will not be implemented.
 security
Security-sensitive issue or fix
 status: backlog
Board: Backlog (synced from the XC_VM board)
 status: in progress
Board: In Progress (synced from the XC_VM board)
 status: post-release verification
Board: released, waiting for confirmation (synced from the XC_VM board)
 status: review & deploy
Board: Review & Deploy, merged and not released yet (synced from the XC_VM board)
 tech-debt
Refactoring / cleanup / technical debt
 under consideration
Idea or proposal awaiting triage and decision.
 wontfix
This will not be worked on
No labels pull-request
Milestone
No items
No Milestone
Projects
Clear projects
No projects
Assignees
Clear assignees
thegame_1980
No Assignees
1 Participants
Notifications
Due Date
No due date set.
Dependencies

No dependencies set.

Reference: Vateron-Media/XC_VM#83