From aa0704d0aea5b079a4d20aefd6ee4d49d64eae6c Mon Sep 17 00:00:00 2001 From: dalance Date: Thu, 26 Oct 2023 12:19:24 +0900 Subject: [PATCH] Add i18n support --- .github/workflows/rbe.yml | 35 ++- .gitignore | 4 +- README.md | 25 +++ TRANSLATING.md | 85 ++++++++ book.toml | 9 + theme/css/language-picker.css | 13 ++ theme/index.hbs | 386 ++++++++++++++++++++++++++++++++++ 7 files changed, 555 insertions(+), 2 deletions(-) create mode 100644 TRANSLATING.md create mode 100644 theme/css/language-picker.css create mode 100644 theme/index.hbs diff --git a/.github/workflows/rbe.yml b/.github/workflows/rbe.yml index 76b127b96d..e93054547e 100644 --- a/.github/workflows/rbe.yml +++ b/.github/workflows/rbe.yml @@ -1,12 +1,19 @@ name: CI on: [push, pull_request] +env: + # Update the language picker in index.hbs to link new languages. + LANGUAGES: + jobs: test: name: Run tests runs-on: ubuntu-latest steps: - - uses: actions/checkout@master + - uses: actions/checkout@v4 + with: + # We need the full history below. + fetch-depth: 0 - name: Update rustup run: rustup self update @@ -23,6 +30,10 @@ jobs: curl -sSL https://github.com/rust-lang/mdBook/releases/download/v0.4.15/mdbook-v0.4.15-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.0 + - name: Report versions run: | rustup --version @@ -41,6 +52,28 @@ jobs: https://raw.githubusercontent.com/rust-lang/rust/master/src/tools/linkchecker/linkcheck.sh sh linkcheck.sh --all rust-by-example + - name: Build all translations + run: | + for po_lang in ${{ env.LANGUAGES }}; do + POT_CREATION_DATE=$(grep --max-count 1 '^"POT-Creation-Date:' po/$po_lang.po | sed -E 's/".*: (.*)\\n"/\1/') + if [[ $POT_CREATION_DATE == "" ]]; then + POT_CREATION_DATE=now + fi + + echo "::group::Building $po_lang translation as of $POT_CREATION_DATE" + rm -r src/ + git restore --source "$(git rev-list -n 1 --before "$POT_CREATION_DATE" @)" src/ + + # Set language and adjust site URL. Clear the redirects + # since they are in sync with the source files, not the + # translation. + MDBOOK_BOOK__LANGUAGE=$po_lang \ + MDBOOK_OUTPUT__HTML__SITE_URL=/rust-by-example/$po_lang/ \ + MDBOOK_OUTPUT__HTML__REDIRECT='{}' \ + mdbook build -d book/$po_lang + echo "::endgroup::" + done + - name: Upload Artifact uses: actions/upload-artifact@v3 with: diff --git a/.gitignore b/.gitignore index e82f879ba9..d88c0391ec 100644 --- a/.gitignore +++ b/.gitignore @@ -1,4 +1,6 @@ book +po/messages.pot + # Auto-generated files from macOS -.DS_Store \ No newline at end of file +.DS_Store diff --git a/README.md b/README.md index 2529a3fad3..ddc1ce455e 100644 --- a/README.md +++ b/README.md @@ -27,12 +27,37 @@ mdbook serve To be able to run the examples, you must be connected to the internet; you can read all content offline, however! +The following warnings can be ignored safely. + +``` +[WARN] (mdbook::preprocess::cmd): The command wasn't found, is the "gettext" preprocessor installed? +[WARN] (mdbook::preprocess::cmd): Command: mdbook-gettext +``` + +### Using translated version + +If there is a translated resource in `po/` directory, it can be specified through `MDBOOK_BOOK__LANGUAGE` like below: + +```bash +git clone https://github.com/rust-lang/rust-by-example +cd rust-by-example +cargo install mdbook +MDBOOK_BOOK__LANGUAGE=ja mdbook build +MDBOOK_BOOK__LANGUAGE=ja mdbook serve +``` + ## Contributing Please see the [CONTRIBUTING.md] file for more details. [CONTRIBUTING.md]: https://github.com/rust-lang/rust-by-example/blob/master/CONTRIBUTING.md +## Translating + +Please see the [TRANSLATING.md] file for more details. + +[TRANSLATING.md]: https://github.com/rust-lang/rust-by-example/blob/master/TRANSLATING.md + ## Translations to other languages * [Chinese](https://github.com/rust-lang-cn/rust-by-example-cn) diff --git a/TRANSLATING.md b/TRANSLATING.md new file mode 100644 index 0000000000..c2a39f51bb --- /dev/null +++ b/TRANSLATING.md @@ -0,0 +1,85 @@ +# Rust by Example 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/rust-by-example/blob/master/CONTRIBUTING.md + +## Translation workflow + +### Preparation + +RBE 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/rbe.yml` and `theme/index.hbs` like below: + +* `rbe.yml` + +```yml +env: + # Update the language picker in index.hbs to link new languages. + LANGUAGES: xx yy zz +``` + +* `index.hbs` + +```html + +``` diff --git a/book.toml b/book.toml index 61fb4057ff..e8364161b2 100644 --- a/book.toml +++ b/book.toml @@ -13,6 +13,15 @@ enable = true [output.html] git-repository-url = "https://github.com/rust-lang/rust-by-example" +additional-css = [ + "theme/css/language-picker.css", +] [rust] edition = "2021" + +[build] +extra-watch-dirs = ["po"] + +[preprocessor.gettext] +after = ["links"] 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/index.hbs b/theme/index.hbs new file mode 100644 index 0000000000..1ae579f391 --- /dev/null +++ b/theme/index.hbs @@ -0,0 +1,386 @@ + + + + + + {{ 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}} + +
+ +