diff --git a/.github/workflows/main.yml b/.github/workflows/main.yml index 1737bce009..b460baa601 100644 --- a/.github/workflows/main.yml +++ b/.github/workflows/main.yml @@ -1,6 +1,10 @@ name: CI on: [push, pull_request] +env: + # Update the language picker in index.hbs to link new languages. + LANGUAGES: + jobs: test: name: Run tests @@ -17,7 +21,7 @@ jobs: - name: Install mdbook run: | mkdir bin - curl -sSL https://github.com/rust-lang/mdBook/releases/download/v0.4.21/mdbook-v0.4.21-x86_64-unknown-linux-gnu.tar.gz | tar -xz --directory=bin + curl -sSL https://github.com/rust-lang/mdBook/releases/download/v0.4.37/mdbook-v0.4.37-x86_64-unknown-linux-gnu.tar.gz | tar -xz --directory=bin echo "$(pwd)/bin" >> "${GITHUB_PATH}" - name: Report versions run: | @@ -64,8 +68,10 @@ jobs: - name: Install mdbook run: | mkdir bin - curl -sSL https://github.com/rust-lang/mdBook/releases/download/v0.4.21/mdbook-v0.4.21-x86_64-unknown-linux-gnu.tar.gz | tar -xz --directory=bin + curl -sSL https://github.com/rust-lang/mdBook/releases/download/v0.4.37/mdbook-v0.4.37-x86_64-unknown-linux-gnu.tar.gz | tar -xz --directory=bin echo "$(pwd)/bin" >> "${GITHUB_PATH}" + - name: Install mdbook-i18n-helpers + run: cargo install mdbook-i18n-helpers --locked --version 0.3.3 - name: Install mdbook-trpl-note run: cargo install --path packages/mdbook-trpl-note - name: Install mdbook-trpl-listing @@ -97,3 +103,17 @@ jobs: https://raw.githubusercontent.com/rust-lang/rust/master/src/tools/linkchecker/linkcheck.sh # Cannot use --all here because of the generated redirect pages aren't available. sh linkcheck.sh book + - name: Build all translations + run: | + for po_lang in ${{ env.LANGUAGES }}; do + echo "::group::Building $po_lang translation" + MDBOOK_BOOK__LANGUAGE=$po_lang \ + mdbook build -d book/$po_lang + echo "::endgroup::" + done + - name: Check all translations for broken links + run: | + for po_lang in ${{ env.LANGUAGES }}; do + MDBOOK_BOOK__LANGUAGE=$po_lang \ + sh linkcheck.sh --all rust-by-example + done diff --git a/.gitignore b/.gitignore index 17127d1142..2cbfc24112 100644 --- a/.gitignore +++ b/.gitignore @@ -4,5 +4,6 @@ book/ .DS_Store target tmp +po/messages.pot .nova diff --git a/README.md b/README.md index 8befc1b31e..3be0610240 100644 --- a/README.md +++ b/README.md @@ -66,6 +66,21 @@ To run the tests: $ mdbook test ``` +The following warnings can be ignored safely if you don't build a translated version. + +``` +[WARN] (mdbook::preprocess::cmd): The command wasn't found, is the "gettext" preprocessor installed? +[WARN] (mdbook::preprocess::cmd): Command: mdbook-gettext +``` + +### Building translated version + +If there is a translated resource in `po/` directory, it can be specified through `MDBOOK_BOOK__LANGUAGE` like below: + +```bash +MDBOOK_BOOK__LANGUAGE=ja mdbook build +``` + ## Contributing We'd love your help! Please see [CONTRIBUTING.md][contrib] to learn about the @@ -85,6 +100,12 @@ isn't strictly fixing an error, it might sit until the next time that we're working on a large revision: expect on the order of months or years. Thank you for your patience! +## Translating + +Please see the [TRANSLATING.md] file for more details. + +[TRANSLATING.md]: https://github.com/rust-lang/book/blob/main/TRANSLATING.md + ### Translations We'd love help translating the book! See the [Translations] label to join in diff --git a/TRANSLATING.md b/TRANSLATING.md new file mode 100644 index 0000000000..bf1c2969da --- /dev/null +++ b/TRANSLATING.md @@ -0,0 +1,98 @@ +# Translation guidelines + +Please see the [CONTRIBUTING.md] file for general contribution guidelines. +This file describes about the translation workflow. + +[CONTRIBUTING.md]: https://github.com/rust-lang/book/blob/main/CONTRIBUTING.md + +## Translation workflow + +### Preparation + +The book uses [mdbook-i18n-helpers](https://github.com/google/mdbook-i18n-helpers) as a translation framework. +The following tools are required. + +* GNU gettext utilities ( `msgmerge` and `msgcat` ) +* mdbook-i18n-helpers ( `cargo install mdbook-i18n-helpers` ) + +### Creating and Updating Translations + +Please see the [mdbook-i18n-helpers USAGE](https://github.com/google/mdbook-i18n-helpers/blob/main/i18n-helpers/USAGE.md) file for the detailed usage of mdbook-i18n-helpers. +The summarized command list is below: + +#### Generating a message template + +The generated message templete `po/messages.pot` is required to create or update translations. + +```bash +MDBOOK_OUTPUT='{"xgettext": {"pot-file": "messages.pot"}}' \ + mdbook build -d po +``` + +#### Creating a new translation resource + +`xx` is [ISO 639](https://en.wikipedia.org/wiki/List_of_ISO_639-1_codes) language code. + +```bash +msginit -i po/messages.pot -l xx -o po/xx.po +``` + +#### Updating the exising translation resource + +```bash +msgmerge --update po/xx.po po/messages.pot +``` + +### Editing translation resources + +After generating a translation resource `po/xx.po`, you can write translation messages in `msgstr` entry of `po/xx.po`. +To build a translated book, the following command can be used. + +```bash +MDBOOK_BOOK__LANGUAGE=xx mdbook build +MDBOOK_BOOK__LANGUAGE=xx mdbook serve +``` + +### Add a language entry + +Please add a language entry in `.github/workflows/main.yml`, `theme/index.hbs`, and `src/bootstrap/src/core/build_steps/doc.rs` in [rust-lang/rust](https://github.com/rust-lang/rust) like below: + +* `main.yml` + +```yml +env: + # Update the language picker in index.hbs to link new languages. + LANGUAGES: xx yy zz +``` + +* `index.hbs` + +```html + +``` + +* `src/bootstrap/src/core/build_steps/doc.rs` in [rust-lang/rust](https://github.com/rust-lang/rust) + +```rust +// build book +builder.ensure(RustbookSrc { + target, + name: "book".to_owned(), + src: absolute_path.clone(), + parent: Some(self), + languages: vec!["xx", "yy", "zz"], +}); +``` diff --git a/book.toml b/book.toml index 800adcf0f5..158b699687 100644 --- a/book.toml +++ b/book.toml @@ -6,7 +6,7 @@ title = "The Rust Programming Language" authors = ["Steve Klabnik", "Carol Nichols", "Contributions from the Rust Community"] [output.html] -additional-css = ["ferris.css", "theme/2018-edition.css", "theme/semantic-notes.css", "theme/listing.css"] +additional-css = ["ferris.css", "theme/css/2018-edition.css", "theme/css/semantic-notes.css", "theme/css/listing.css", "theme/css/language-picker.css"] additional-js = ["ferris.js"] git-repository-url = "https://github.com/rust-lang/book" @@ -18,3 +18,9 @@ output-mode = "default" [rust] edition = "2021" + +[build] +extra-watch-dirs = ["po"] + +[preprocessor.gettext] +after = ["links"] diff --git a/theme/2018-edition.css b/theme/css/2018-edition.css similarity index 100% rename from theme/2018-edition.css rename to theme/css/2018-edition.css diff --git a/theme/css/language-picker.css b/theme/css/language-picker.css new file mode 100644 index 0000000000..1553ed68fe --- /dev/null +++ b/theme/css/language-picker.css @@ -0,0 +1,13 @@ +#language-list { + left: auto; + right: 10px; +} + +[dir="rtl"] #language-list { + left: 10px; + right: auto; +} + +#language-list a { + color: inherit; +} diff --git a/theme/listing.css b/theme/css/listing.css similarity index 100% rename from theme/listing.css rename to theme/css/listing.css diff --git a/theme/semantic-notes.css b/theme/css/semantic-notes.css similarity index 100% rename from theme/semantic-notes.css rename to theme/css/semantic-notes.css diff --git a/theme/index.hbs b/theme/index.hbs new file mode 100644 index 0000000000..bae3ea4b61 --- /dev/null +++ b/theme/index.hbs @@ -0,0 +1,388 @@ + + + + + + {{ title }} + {{#if is_print }} + + {{/if}} + {{#if base_url}} + + {{/if}} + + + + {{> head}} + + + + + + {{#if favicon_svg}} + + {{/if}} + {{#if favicon_png}} + + {{/if}} + + + + {{#if print_enable}} + + {{/if}} + + + + {{#if copy_fonts}} + + {{/if}} + + + + + + + + {{#each additional_css}} + + {{/each}} + + {{#if mathjax_support}} + + + {{/if}} + + +
+ + + + + + + + + + + + + + + + + + + +
+ +
+ {{> header}} + + + + {{#if search_enabled}} + + {{/if}} + + + + +
+
+ {{{ content }}} +
+ + +
+
+ + + +
+ + {{#if live_reload_endpoint}} + + + {{/if}} + + {{#if google_analytics}} + + + {{/if}} + + {{#if playground_line_numbers}} + + {{/if}} + + {{#if playground_copyable}} + + {{/if}} + + {{#if playground_js}} + + + + + + {{/if}} + + {{#if search_js}} + + + + {{/if}} + + + + + + + {{#each additional_js}} + + {{/each}} + + {{#if is_print}} + {{#if mathjax_support}} + + {{else}} + + {{/if}} + {{/if}} + +
+ +