概述

cargo-doc-l10n工具允许翻译rustdoc文档中使用的doc注释，并在原始代码演变时帮助保持翻译尽可能准确。

主要目标是

• 引入一个对Rust开发者来说自然的doc注释本地化标准格式。
• 翻译工作不应影响开发者
  • 在源代码中使用doc注释的方式没有变化。
  • 本地化文件位于单独的目录中，开发者无需关心。
  • 他们只需使用cargo doc-l10n代替cargo doc来生成与原始文档一起的本地化文档。
• 当生成文档时，你会收到关于翻译过时或缺失的项目警告。
• 翻译的文档包含警告和引用当前原始文本的项目过时翻译。
• 翻译必须能够轻松地找到所有过时的翻译。

它如何工作

当rustdoc工具从源代码中的doc注释（位于/src目录）获取文档文本时，cargo-doc-l10n工具从位于/l10n/{lang}/doc/src的doc注释文件中获取文档文本，这些文件模仿原始源文件。

该工具帮助保持这些文件与源文件的一致性

指南

安装cargo-doc-l10n

只需运行cargo install cargo-doc-l10n

提供新语言的翻译

如果您有一个crate并且希望为新的语言提供文档翻译，请在crate目录的根目录中运行以下命令

cargo doc-l10n add {lang}

其中 {lang} 是语言的 ISO-639-1 代码。[ISO-639-1 代码列表]。它将在 /l10n/{lang}/doc/src 目录下创建一组文件，与 /src 目录中的文件相匹配，但与扩展名为 .rs 的常规源文件不同，这些是具有 .loc.rs 扩展名的本地化文件。这些本地化文件类似于 Rust 代码，包含在匹配的 rs 文件中记录的项目声明，但文档注释将包含翻译。原始文档注释保留在标签后面（这将有助于检测更改）。

例如，一个库的法语和西班牙语本地化版本的 crate 目录，只有一个名为“my_mod”的模块，应该看起来像这样

+-src
| +-my_mod
| | +-mod.rs
| +-lib.rs
+-l10n
  +-es
  | +-doc
  |   +-src
  |     +-my_mod
  |     | +-mod.loc.rs
  |     +-lib.loc.rs
  +-fr
    +-doc
      +-src
        +-my_mod
        | +-mod.loc.rs
        +-lib.loc.rs

对于原始源代码中记录的每个项目，匹配的本地化文件中的文档注释将包含一个空行以填写翻译，随后是原始文档注释的内容，位于 [l10n] # (original) 标签行后面。

例如，给定原始源中的这个 src/lib.rs 文件

/// The main struct of the library
struct MainStruct {
  /// The only field of MainStruct
  field : u32,
}

impl MainStruct {
  /// Do something interesting
  fn do_something(&mut self) {
    self.field += 1;
  }
  fn undocumented_fn(&self){
    println!("Hello World !"); 
  }
}

为法语本地化生成的 /l10n/fr/doc/src/lib.loc.rs 文件将看起来像这样

///
///[l10n] # (original)
/// The main struct of the library
struct MainStruct {

  ///
  ///[l10n] # (original)
  /// The only field of MainStruct
  field : u32,
}

impl MainStruct {

  ///
  ///[l10n] # (original)
  /// Do something interesting
  fn do_something(&mut self) {}
}

您必须在 [l10n] # (original) 之前填写翻译空间。不要修改或删除 original 部分：它将用于检查源代码中文档注释的翻译是否在翻译之后发生修改。一旦填写完“lib.loc.rs”文件，它应该看起来像这样

/// La struct principale de la bibliothèque
///[l10n] # (original)
/// The main struct of the library
struct MainStruct {

  /// Le seul champ de la bibliothèque
  ///[l10n] # (original)
  /// The only field of MainStruct
  field : u32,
}

impl MainStruct {
 
  /// Fait quelquechose d'intéressant
  ///[l10n] # (original)
  /// Do something interesting
  fn do_something(&mut self) {}
}

生成翻译后的文档

当您运行 cargo doc-l10n 命令时，将生成所有可用区域设置的文档，包括原始文档。如果您只想为一种语言生成文档，请运行 cargo doc-l10n {lang}。

如果源代码中记录的项目在本地化文件中没有匹配项，或者匹配项的翻译为空，您将在命令行上收到关于缺少翻译的警告。将使用原始文本为此项目。

如果源代码中记录的项目在本地化文件中有匹配项，但源代码中的文档注释不包含与本地化文件中 [l10n] # (original) 行后面的部分相同的文本，您将在命令行上收到关于过时翻译的警告。将使用原始文本为此项目。

修复过时的翻译

如果源代码发生变化并且您想修复翻译以匹配，首先运行命令 cargo doc-l10n update {lang}。指定语言的本地化文件内容将自动更新以匹配新的源代码，并且您将在命令行上收到关于需要更新的本地化文件部分的警告。

• 自上次翻译以来添加到源代码中的项目，将插入到 ".loc.rs" 文件中，通常的空白部分需要填写，而 [l10n] # (original) 部分保持不变。

• 对于实际源代码中的文档注释与 [l10n] # (original) 行后面的内容不再匹配的项目

  • 之前的翻译保持不变
  • 将会有一个 [l10n] # (outdated) 行。该行后面的部分包含之前的原始部分。
  • [l10n] # (original) 后面的部分包含新的原始文档注释。

例如，如果之前的 lib.rs 文件被修改为

/// The main struct of the library
struct MainStruct {

  /// The first field of MainStruct
  field : u32,
  
  /// An additional field
  additional_field : u32,
}

impl MainStruct {

  /// Do something interesting
  fn do_something(&mut self) {
    self.field += 1;
  }
  
  /// Do something else interesting
  fn do_something_else(&self){
    self.additional_field += 1;
  }
}

更新后的 “lib.loc.rs” 将看起来像这样

///La struct principale de la bibliothèque
///[l10n] # (original)
///The main struct of the library
struct MainStruct {
  
  ///Le seul champ de la bibliothèque
  ///[l10n] # (outdated)
  ///The only field of MainStruct
  ///[l10n] # (original)
  ///The first field of MainStruct
  field : u32,
  
  ///
  ///[l10n] # (original)
  ///An additional field
  additional_field : u32,
}

impl MainStruct {
  /// Fait quelquechose d'intéressant
  ///[l10n] # (original)
  /// Do something interesting
}

填写空白部分的翻译。

更新具有 doc_outdated 部分的项目的翻译。然后，一旦完成修复翻译，就删除 doc_outdated 部分。

您可以再次运行 cargo doc-l10n update {lang} 以检查是否还有警告。