+ Translation prompt for your AI Agent +
+ +# Translation Style Guide + +## 1. Tone & Voice + +### Preserve original tone + +Maintain the author's attitude, formality, and emotional register exactly as in the source. + +### Synonymous substitution + +Use words with close or equivalent meaning where direct translation is awkward or unnatural. + +## 2. Vocabulary & Abbreviation + +### Abbreviation + +Apply standard English abbreviations (e.g., _info_ for information, _dept_ for department) +to avoid overlong words, +but only when clarity is not sacrificed. + +### Concise expression + +Prefer shorter, more common alternatives (e.g., _use_ over _utilize_, _help_ over _facilitate_) +unless the original tone demands formality. + +## 3. Structural Rules + +### Paragraph integrity + +Keep the original paragraph breaks and line spacing. + +### Tag preservation + +Any inline Markdown formatting (bold, italic, code, links, lists) must be replicated exactly in translation. + +### Example + +- Before: “请保持专业语气，但避免使用过长的学术词汇。” +- After: “Keep a prof. tone, but avoid long academic words.” + +### Minimal diff + +When translating or syncing English content against a known Chinese original, +if the Chinese original's meaning is extremely close to the current English meaning, +do not modify the English text. +This is to keep git diffs friendly _(only modify parts that have truly changed)_. + +## 4. Exceptions + +- If a term has no common abbreviation, use the full word. +- If preserving tone requires a longer phrase, prioritize tone over brevity. + +## 5. Original Text + +```markdown +# Translation Style Guide + +## 1. Tone & Voice + +### Preserve original tone + +Maintain the author's attitude, formality, and emotional register exactly as in the source. + +### Synonymous substitution + +Use words with close or equivalent meaning where direct translation is awkward or unnatural. + +## 2. Vocabulary & Abbreviation + +### Abbreviation + +Apply standard English abbreviations (e.g., _info_ for information, _dept_ for department) +to avoid overlong words, +but only when clarity is not sacrificed. + +### Concise expression + +Prefer shorter, more common alternatives (e.g., _use_ over _utilize_, _help_ over _facilitate_) +unless the original tone demands formality. + +## 3. Structural Rules + +### Paragraph integrity + +Keep the original paragraph breaks and line spacing. + +### Tag preservation + +Any inline Markdown formatting (bold, italic, code, links, lists) must be replicated exactly in translation. + +### Example + +- Before: “请保持专业语气，但避免使用过长的学术词汇。” +- After: “Keep a prof. tone, but avoid long academic words.” + +### Minimal diff + +When translating or syncing English content against a known Chinese original, +if the Chinese original's meaning is extremely close to the current English meaning, +do not modify the English text. +This is to keep git diffs friendly _(only modify parts that have truly changed)_. + +## 4. Exceptions + +- If a term has no common abbreviation, use the full word. +- If preserving tone requires a longer phrase, prioritize tone over brevity. +``` + ++ Written by @Weicao-CatilGrass +
diff --git a/docs/dev/pages/abouts/code-verify-system.md b/docs/dev/pages/abouts/code-verify-system.md new file mode 100644 index 0000000..61b66e8 --- /dev/null +++ b/docs/dev/pages/abouts/code-verify-system.md @@ -0,0 +1,242 @@ ++ A system that verifies every identified code block can be compiled +
+ +This system automatically extracts and compiles Rust code blocks from docs, ensuring all example code stays usable in CI. + +## Config + +Specify which Markdown files to verify via [`verified-docs.toml`](https://github.com/mingling-rs/mingling/blob/main/verified-docs.toml) in the project root. + +You can also test a single file via command-line arg: + +```sh +./run-tools.sh test-all-markdown-code docs/pages/1-getting-started.md +``` + +```powershell +.\run-tools.ps1 test-all-markdown-code docs/pages/1-getting-started.md +``` + +## Default Rules + +Every verified ` ```rust ` code block gets the following injected automatically at compile time — no need to write them explicitly in the block: + +### 1. `#![allow(dead_code)]` and `#![allow(unused)]` + +Added at the top of the generated `main.rs` to suppress dead-code warnings from partial code snippets. + +### 2. `use mingling::prelude::*;` + +If the block already has `use mingling::prelude::*;`, it won't be inserted again. + +Otherwise it's inserted automatically (with `#[allow(unused_imports)]`). + +### 3. `fn main() {}` + +If the block **does not contain** a `fn main` definition, an empty `fn main() {}` is appended, + +so the block can compile as a standalone binary project. + +### 4. `mingling::macros::gen_program!();` + +If the block **does not contain** a `gen_program!()` call, + +`mingling::macros::gen_program!();` is appended automatically. + +This call is required by the mingling framework. + +### 5. Build Cache Dedup — Shared Dep Hash + +Code blocks with the same `Features` and `Dependencies` are automatically grouped into the same compile group, sharing one `Cargo.toml` and build artifacts, avoiding redundant compilations. + +> [!NOTE] +> +> Hash input (all sorted): +> +> 1. Feature list +> 2. External dep name list +> 3. External dep version list +> 4. `name=version` pairs +> +> Uses FNV-1a 64-bit hash, stable across runs. + +## Verification Steps + +After the **default rules** are applied, each block goes through: + +### 1. Block Extraction + +- Only ` ```rust ` fenced code blocks are extracted. +- Empty blocks (no code lines) are skipped. +- Blocks with `// NOT VERIFIED` alone are skipped. + +### 2. Temp Project Generation + +Each block (or each dedup-hash group) gets its own Cargo project: + +``` +.temp/doc-test/