Skip to content

Commit f5cebc3

Browse files
dalancedalance
committed
Add translation support
1 parent 5228bfa commit f5cebc3

File tree

10 files changed

+550
-3
lines changed

10 files changed

+550
-3
lines changed

‎.github/workflows/main.yml

+22-2
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,10 @@
11
name: CI
22
on: [push, pull_request]
33

4+
env:
5+
# Update the language picker in index.hbs to link new languages.
6+
LANGUAGES:
7+
48
jobs:
59
test:
610
name: Run tests
@@ -17,7 +21,7 @@ jobs:
1721
- name: Install mdbook
1822
run: |
1923
mkdir bin
20-
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
24+
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
2125
echo "$(pwd)/bin" >> ${GITHUB_PATH}
2226
- name: Report versions
2327
run: |
@@ -64,8 +68,10 @@ jobs:
6468
- name: Install mdbook
6569
run: |
6670
mkdir bin
67-
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
71+
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
6872
echo "$(pwd)/bin" >> ${GITHUB_PATH}
73+
- name: Install mdbook-i18n-helpers
74+
run: cargo install mdbook-i18n-helpers --locked --version 0.3.3
6975
- name: Install mdbook-trpl-note
7076
run: cargo install --path packages/mdbook-trpl-note
7177
- name: Install mdbook-trpl-listing
@@ -97,3 +103,17 @@ jobs:
97103
https://raw.githubusercontent.com/rust-lang/rust/master/src/tools/linkchecker/linkcheck.sh
98104
# Cannot use --all here because of the generated redirect pages aren't available.
99105
sh linkcheck.sh book
106+
- name: Build all translations
107+
run: |
108+
for po_lang in ${{ env.LANGUAGES }}; do
109+
echo "::group::Building $po_lang translation"
110+
MDBOOK_BOOK__LANGUAGE=$po_lang \
111+
mdbook build -d book/$po_lang
112+
echo "::endgroup::"
113+
done
114+
- name: Check all translations for broken links
115+
run: |
116+
for po_lang in ${{ env.LANGUAGES }}; do
117+
MDBOOK_BOOK__LANGUAGE=$po_lang \
118+
sh linkcheck.sh --all rust-by-example
119+
done

‎.gitignore

+1
Original file line numberDiff line numberDiff line change
@@ -4,4 +4,5 @@ book/
44
.DS_Store
55
target
66
tmp
7+
po/messages.pot
78

‎README.md

+21
Original file line numberDiff line numberDiff line change
@@ -66,6 +66,21 @@ To run the tests:
6666
$ mdbook test
6767
```
6868

69+
The following warnings can be ignored safely if you don't build a translated version.
70+
71+
```
72+
[WARN] (mdbook::preprocess::cmd): The command wasn't found, is the "gettext" preprocessor installed?
73+
[WARN] (mdbook::preprocess::cmd): Command: mdbook-gettext
74+
```
75+
76+
### Building translated version
77+
78+
If there is a translated resource in `po/` directory, it can be specified through `MDBOOK_BOOK__LANGUAGE` like below:
79+
80+
```bash
81+
MDBOOK_BOOK__LANGUAGE=ja mdbook build
82+
```
83+
6984
## Contributing
7085

7186
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
85100
working on a large revision: expect on the order of months or years. Thank you
86101
for your patience!
87102

103+
## Translating
104+
105+
Please see the [TRANSLATING.md] file for more details.
106+
107+
[TRANSLATING.md]: https://github.com/rust-lang/book/blob/main/TRANSLATING.md
108+
88109
### Translations
89110

90111
We'd love help translating the book! See the [Translations] label to join in

‎TRANSLATING.md

+98
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,98 @@
1+
# Translation guidelines
2+
3+
Please see the [CONTRIBUTING.md] file for general contribution guidelines.
4+
This file describes about the translation workflow.
5+
6+
[CONTRIBUTING.md]: https://github.com/rust-lang/book/blob/main/CONTRIBUTING.md
7+
8+
## Translation workflow
9+
10+
### Preparation
11+
12+
The book uses [mdbook-i18n-helpers](https://github.com/google/mdbook-i18n-helpers) as a translation framework.
13+
The following tools are required.
14+
15+
* GNU gettext utilities ( `msgmerge` and `msgcat` )
16+
* mdbook-i18n-helpers ( `cargo install mdbook-i18n-helpers` )
17+
18+
### Creating and Updating Translations
19+
20+
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.
21+
The summarized command list is below:
22+
23+
#### Generating a message template
24+
25+
The generated message templete `po/messages.pot` is required to create or update translations.
26+
27+
```bash
28+
MDBOOK_OUTPUT='{"xgettext": {"pot-file": "messages.pot"}}' \
29+
mdbook build -d po
30+
```
31+
32+
#### Creating a new translation resource
33+
34+
`xx` is [ISO 639](https://en.wikipedia.org/wiki/List_of_ISO_639-1_codes) language code.
35+
36+
```bash
37+
msginit -i po/messages.pot -l xx -o po/xx.po
38+
```
39+
40+
#### Updating the exising translation resource
41+
42+
```bash
43+
msgmerge --update po/xx.po po/messages.pot
44+
```
45+
46+
### Editing translation resources
47+
48+
After generating a translation resource `po/xx.po`, you can write translation messages in `msgstr` entry of `po/xx.po`.
49+
To build a translated book, the following command can be used.
50+
51+
```bash
52+
MDBOOK_BOOK__LANGUAGE=xx mdbook build
53+
MDBOOK_BOOK__LANGUAGE=xx mdbook serve
54+
```
55+
56+
### Add a language entry
57+
58+
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:
59+
60+
* `main.yml`
61+
62+
```yml
63+
env:
64+
# Update the language picker in index.hbs to link new languages.
65+
LANGUAGES: xx yy zz
66+
```
67+
68+
* `index.hbs`
69+
70+
```html
71+
<ul id="language-list" class="theme-popup" aria-label="Languages" role="menu">
72+
<li role="none"><button role="menuitem" class="theme">
73+
<a id="en">English</a>
74+
</button></li>
75+
<li role="none"><button role="menuitem" class="theme">
76+
<a id="xx">XX language</a>
77+
</button></li>
78+
<li role="none"><button role="menuitem" class="theme">
79+
<a id="yy">YY language</a>
80+
</button></li>
81+
<li role="none"><button role="menuitem" class="theme">
82+
<a id="zz">ZZ language</a>
83+
</button></li>
84+
</ul>
85+
```
86+
87+
* `src/bootstrap/src/core/build_steps/doc.rs` in [rust-lang/rust](https://github.com/rust-lang/rust)
88+
89+
```rust
90+
// build book
91+
builder.ensure(RustbookSrc {
92+
target,
93+
name: "book".to_owned(),
94+
src: absolute_path.clone(),
95+
parent: Some(self),
96+
languages: vec!["xx", "yy", "zz"],
97+
});
98+
```

‎book.toml

+7-1
Original file line numberDiff line numberDiff line change
@@ -6,7 +6,7 @@ title = "The Rust Programming Language"
66
authors = ["Steve Klabnik", "Carol Nichols", "Contributions from the Rust Community"]
77

88
[output.html]
9-
additional-css = ["ferris.css", "theme/2018-edition.css", "theme/semantic-notes.css", "theme/listing.css"]
9+
additional-css = ["ferris.css", "theme/css/2018-edition.css", "theme/css/semantic-notes.css", "theme/css/listing.css", "theme/css/language-picker.css"]
1010
additional-js = ["ferris.js"]
1111
git-repository-url = "https://github.com/rust-lang/book"
1212

@@ -15,3 +15,9 @@ git-repository-url = "https://github.com/rust-lang/book"
1515

1616
[preprocessor.trpl-listing]
1717
output-mode = "default"
18+
19+
[build]
20+
extra-watch-dirs = ["po"]
21+
22+
[preprocessor.gettext]
23+
after = ["links"]

‎theme/2018-edition.css renamed to ‎theme/css/2018-edition.css

File renamed without changes.

‎theme/css/language-picker.css

+13
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,13 @@
1+
#language-list {
2+
left: auto;
3+
right: 10px;
4+
}
5+
6+
[dir="rtl"] #language-list {
7+
left: 10px;
8+
right: auto;
9+
}
10+
11+
#language-list a {
12+
color: inherit;
13+
}

‎theme/listing.css renamed to ‎theme/css/listing.css

File renamed without changes.

‎theme/semantic-notes.css renamed to ‎theme/css/semantic-notes.css

File renamed without changes.

0 commit comments

Comments
 (0)