docs: rewrite translations contributing guide for Crowdin#651
Conversation
Replace manual PO/FTL translation walkthroughs with a Crowdin-first two-page structure: an overview for translators (architecture, CI sync, build-time wiring for UI, mdBook, and website) and a developer guide for adding English strings, regenerating messages.pot, and i18n:skip directives. Simplify devenv.nix translation messaging and remove Poedit from the development environment. Co-authored-by: Kevin <OGKevin@users.noreply.github.com>
Drop 'chrome' and 'portal' in favour of 'website', and clarify that i18n:skip directives apply to mdBook documentation extraction only. Co-authored-by: Kevin <OGKevin@users.noreply.github.com>
Co-authored-by: Kevin <OGKevin@users.noreply.github.com>
The EPUB preprocessor always used ../mermaid-images/, which resolves incorrectly for chapters nested below src/ (e.g. contributing/translations/). Compute the relative path from each chapter file instead. Fixes cadmus-docs build failure on translations/index.md mermaid diagram. Co-authored-by: Kevin <OGKevin@users.noreply.github.com>
dosubot
Bot
added
size:XL
|
No actionable comments were generated in the recent review. 🎉 ℹ️ Recent review info⚙️ Run configurationConfiguration used: Repository YAML (base), Organization UI (inherited) Review profile: CHILL Plan: Pro Plus Run ID: 📒 Files selected for processing (1)
🚧 Files skipped from review as they are similar to previous changes (1)
📜 Recent review details⏰ Context from checks skipped due to timeout. (3)
|
| Check name | Status | Explanation |
|---|---|---|
| Title check | ✅ Passed | The title follows Conventional Commits and accurately summarizes the docs-focused Crowdin translation guide rewrite. |
| Docstring Coverage | ✅ Passed | No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check. |
| Linked Issues check | ✅ Passed | Check skipped because no linked issues were found for this pull request. |
| Out of Scope Changes check | ✅ Passed | Check skipped because no linked issues were found for this pull request. |
Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.
Comment @coderabbitai help to get the list of available commands.
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
🧹 Nitpick comments (1)
docs/mdbook-mermaid-preprocessor.py (1)
119-132: 📐 Maintainability & Code Quality | 🔵 Trivial | 💤 Low valueDocument the new
chapter_pathparameter in the docstring.The
Argssection listscontent,chapter_name, andpng_dirbut omits the newly addedchapter_pathparameter.📝 Proposed fix
Args: content: The markdown content of the chapter chapter_name: Name of the chapter (for PNG filenames) png_dir: Directory where PNG files should be saved + chapter_path: Path of the chapter relative to src/ (used for relative image links)🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the rest with a brief reason, keep changes minimal, and validate. In `@docs/mdbook-mermaid-preprocessor.py` around lines 119 - 132, Update the docstring for process_chapter_content to include the newly added chapter_path parameter in the Args section. Keep the existing descriptions for content, chapter_name, and png_dir, and add a concise explanation of chapter_path so the documented signature matches the function definition.
🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
Nitpick comments:
In `@docs/mdbook-mermaid-preprocessor.py`:
- Around line 119-132: Update the docstring for process_chapter_content to
include the newly added chapter_path parameter in the Args section. Keep the
existing descriptions for content, chapter_name, and png_dir, and add a concise
explanation of chapter_path so the documented signature matches the function
definition.
ℹ️ Review info
⚙️ Run configuration
Configuration used: Repository YAML (base), Organization UI (inherited)
Review profile: CHILL
Plan: Pro Plus
Run ID: cc21f89a-182a-4d53-9c39-43d71d6d8cf0
📒 Files selected for processing (7)
devenv.nixdocs/mdbook-mermaid-preprocessor.pydocs/src/SUMMARY.mddocs/src/contributing/translations/developers.mddocs/src/contributing/translations/docs.mddocs/src/contributing/translations/index.mddocs/src/contributing/translations/source-code.md
💤 Files with no reviewable changes (2)
- docs/src/contributing/translations/source-code.md
- docs/src/contributing/translations/docs.md
📜 Review details
⚠️ CI failures not shown inline (1)
GitHub Actions: PR #651 / 2_Analyze (rust).txt: PR #651
Conclusion: failure
##[group]Extracting rust
[command]/opt/hostedtoolcache/CodeQL/2.25.6/x64/codeql/codeql database trace-command --use-build-mode --working-dir /home/runner/work/cadmus/cadmus /home/runner/work/_temp/codeql_databases/rust
Running command in /home/runner/work/cadmus/cadmus: [/opt/hostedtoolcache/CodeQL/2.25.6/x64/codeql/rust/tools/autobuild.sh]
[] [build-stderr] Scanning for files in /home/runner/work/cadmus/cadmus...
[] [build-stderr] /home/runner/work/_temp/codeql_databases/rust: Indexing files in in /home/runner/work/cadmus/cadmus...
[] [build-stderr] Running command in /home/runner/work/cadmus/cadmus: [/opt/hostedtoolcache/CodeQL/2.25.6/x64/codeql/rust/tools/index-files.sh, /home/runner/work/_temp/codeql_databases/rust/working/files-to-index12105273475609170889.list]
[] [build-stdout] [] [build-stdout] �[32m INFO�[0m configuration: {
[] [build-stdout] [] [build-stdout] scratch_dir: "/home/runner/work/_temp/codeql_databases/rust/working",
[] [build-stdout] [] [build-stdout] trap_dir: "/home/runner/work/_temp/codeql_databases/rust/trap/rust",
[] [build-stdout] [] [build-stdout] source_archive_dir: "/home/runner/work/_temp/codeql_databases/rust/src",
[] [build-stdout] [] [build-stdout] diagnostic_dir: "/home/runner/work/_temp/codeql_databases/rust/diagnostic/extractors/rust",
[] [build-stdout] [] [build-stdout] cargo_target_dir: None,
[] [build-stdout] [] [build-stdout] cargo_target: None,
[] [build-stdout] [] [build-stdout] cargo_features: [],
[] [build-stdout] [] [build-stdout] cargo_cfg_overrides: [],
[] [build-stdout] [] [build-stdout] cargo_extra_env: {},
[] [build-stdout] [] [build-stdout] cargo_extra_args: [],
[] [build-stdout] [] [build-stdout] cargo_all_targets: false,
[] [build-stdout] [] [build-stdout] logging_flamegraph: None,
[] [build-stdout] [] [build-stdout] logging_verbosity: Some(
[] [build-stdout] [] [build-stdout] "progress",
[] [build-stdout] [] [build-stdout] )...
🧰 Additional context used
📓 Path-based instructions (3)
docs/src/**/*.md
📄 CodeRabbit inference engine (docs/AGENTS.md)
docs/src/**/*.md: Use conversational and friendly tone in user-facing documentation
Use active voice in user-facing documentation (e.g., 'Copy the file' instead of 'The file should be copied')
Avoid jargon in user-facing documentation: replace 'artifact' with 'file' or 'package', 'deploy' with 'install' or 'download', 'configure' with 'set up', 'bundle' with 'package', 'on-device' with 'on your Kobo' or 'wirelessly'
Use standardized admonition syntax for documentation: [!NOTE], [!TIP], [!IMPORTANT], [!WARNING], [!CAUTION]Regenerate the POT file (
docs/po/messages.pot) when any English doc source (docs/src/**/*.md) is modified
Files:
docs/src/SUMMARY.mddocs/src/contributing/translations/developers.mddocs/src/contributing/translations/index.md
docs/**/*.md
📄 CodeRabbit inference engine (docs/AGENTS.md)
docs/**/*.md: Format Markdown with Prettier
Ensure Markdown passes markdownlint
Use code blocks with language tags in Markdown
docs/**/*.md: Format Markdown with Prettier
Ensure Markdown passes markdownlint validation
Files:
docs/src/SUMMARY.mddocs/src/contributing/translations/developers.mddocs/src/contributing/translations/index.md
docs/src/contributing/**/*.md
📄 CodeRabbit inference engine (docs/AGENTS.md)
docs/src/contributing/**/*.md: Use clear and direct language in contributor documentation with code examples where helpful
Document setup steps precisely in contributor documentation
Files:
docs/src/contributing/translations/developers.mddocs/src/contributing/translations/index.md
🧠 Learnings (1)
📚 Learning: 2026-05-31T07:53:12.579Z
Learnt from: OGKevin
Repo: OGKevin/cadmus PR: 553
File: docs/src/installation/migration.md:87-88
Timestamp: 2026-05-31T07:53:12.579Z
Learning: For markdown files under docs/src/ in the cadmus (OGKevin/cadmus) repo, validate mdBook admonition syntax using the allowed types: NOTE, TIP, WARNING, IMPORTANT, and CAUTION. The correct format is a blockquote prefix like `> [!NOTE]`, `> [!TIP]`, `> [!WARNING]`, `> [!IMPORTANT]`, or `> [!CAUTION]`. Do not flag `[!CAUTION]` or `[!IMPORTANT]` as non-standard in this repo.
Applied to files:
docs/src/SUMMARY.mddocs/src/contributing/translations/developers.mddocs/src/contributing/translations/index.md
🪛 LanguageTool
docs/src/contributing/translations/developers.md
[style] ~67-~67: Using many exclamation marks might seem excessive (in this case: 5 exclamation marks for a text that’s 2352 characters long)
Context: ...ll not appear in the POT file. ``` Use <!-- i18n:skip-start --> / `` to exclude multipl...
(EN_EXCESSIVE_EXCLAMATION)
🔇 Additional comments (7)
docs/mdbook-mermaid-preprocessor.py (3)
109-116: LGTM!
143-143: LGTM!
178-183: LGTM!devenv.nix (1)
387-387: LGTM!Also applies to: 391-391, 803-804, 818-818
docs/src/SUMMARY.md (1)
41-41: LGTM!docs/src/contributing/translations/developers.md (1)
15-18: 🎯 Functional CorrectnessVerify the compile-time validation claim.
The visible i18n snippets only show locale embedding and runtime loader selection; they don't show
cargo check -p cadmus-corevalidating message IDs. If that check happens elsewhere, please link it here.docs/src/contributing/translations/index.md (1)
61-63: 🎯 Functional CorrectnessReword the
fl!()description.
crates/core/src/i18n.rsshows embedded FTL assets and a runtime loader;fl!()does not appear to resolve IDs at compile time. Please confirm the wording against the macro behavior.
Co-authored-by: Kevin <OGKevin@users.noreply.github.com>
2 participants
Replace manual PO/FTL translation walkthroughs with a Crowdin-first
two-page structure: an overview for translators (architecture, CI sync,
build-time wiring for UI, mdBook, and website) and a developer guide
for adding English strings, regenerating messages.pot, and i18n:skip
directives.
Simplify devenv.nix translation messaging and remove Poedit from the
development environment.