mdbook-transcheck

翻译版 mdbook 的检查器

安装

$ cargo install mdbook-transcheck

用法

检查

以下命令检查 src 和 tgt 是否同步。

$ mdbook-transcheck src tgt

src 是原始 mdbook 的源目录。 tgt 是翻译版 mdbook 的源目录。

修复

以下命令将 src 和 tgt 之间的差异应用到 tgt。

$ mdbook-transcheck --fix src tgt

代码检查

以下命令检查翻译文本是否满足代码检查规则。

$ mdbook-transcheck --lint src tgt

配置

配置文件是 transcheck.toml，位于仓库根目录。

excludes = ["img/"]
[matcher]
enable_code_comment_tweak = true
code_comment_header = "# "
[linter]
enable_emphasis_check = true
enable_half_paren_check = true
enable_full_paren_check = true

根部分

[matcher] 部分

[linter] 部分

示例

$ mdbook-transcheck ./testcase/original ./testcase/translated

Error: target path is not found
    source path: ./testcase/original/missing_file.md
    target path: ./testcase/translated/missing_file.md


Error: source line has been modified
 source --> ./testcase/original/mismatch_lines.md:5
  |
5 | This is an orange.
  |            ^^ ^^
  |

 target --> ./testcase/translated/mismatch_lines.md:11
   |
11 | This is an apple.
   |             ^^^
   |


Error: lines has been inserted to the source file
 source --> ./testcase/original/mismatch_lines.md:2
  |
2 | Orange
  |
  = hint: The lines should be inserted at ./testcase/translated/mismatch_lines.md:2


Error: lines has been removed from the source file
 target --> ./testcase/translated/mismatch_lines.md:4
  |
4 | Lemon
  |

Markdown 规则

翻译的 Markdown 应遵循一些规则。

• 保留原始行
• 使用 <!-- 和 --> 注释掉原始行

简单示例

• 原始

Apple
Orange
Peach

• 翻译

<!--
Apple
Orange
Peach
-->
りんご
オレンジ
桃

以下是不正确的，因为 <!-- Apple 和 Peach --> 与原始行不匹配。

<!-- Apple
Orange
Peach -->
りんご
オレンジ
桃

Markdown 注释

如果原始文本有 Markdown 注释，应在翻译文本中删除注释，因为嵌套注释不受支持。默认情况下忽略删除注释的差异。

• 原始

Apple <!-- ignore -->
Or<!-- ignore -->ange
<!-- ignore -->Peach

• 翻译

<!--
Apple 
Orange
Peach
-->
りんご
オレンジ
桃

如果您想保留注释，可以使用 keep_markdown_comment、markdown_comment_begin 和 markdown_comment_end，如下所示：

keep_markdown_comment = true
markdown_comment_begin = "((("
markdown_comment_end = ")))"

• 原始

Apple <!-- ignore -->
Or<!-- ignore -->ange
<!-- ignore -->Peach

• 翻译

<!--
Apple ((( ignore )))
Or((( ignore )))ange
((( ignore )))Peach
-->
りんご
オレンジ
桃

代码块

• 原始

```rust
// comment
let a = b; // comment
```

• 翻译

```rust
// comment
// コメント
let a = b; // comment
           // コメント
```

您可以使用 # 隐藏原始注释。应将 enable_code_comment_tweak 设置为 true，并将 code_comment_header 设置为 # 。

```rust
# // comment
// コメント
let a = b; // comment
           // コメント
```

您可以使用 # // 隐藏原始代码和注释。应将 enable_code_comment_tweak 设置为 true，并将 code_comment_header 设置为 # // 。

```rust
# // // comment
// コメント
# // let a = b; // comment
let a = b; // コメント
```