Skip to content

Commit 32f5fa0

Browse files
marioidivalmarioidival
authored
Merge pull request #1760 from dalance/i18n
Add i18n support
2 parents 98a8063 + aa0704d commit 32f5fa0

File tree

7 files changed

+555
-2
lines changed

7 files changed

+555
-2
lines changed

‎.github/workflows/rbe.yml

+34-1
Original file line numberDiff line numberDiff line change
@@ -1,12 +1,19 @@
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
711
runs-on: ubuntu-latest
812
steps:
9-
- uses: actions/checkout@master
13+
- uses: actions/checkout@v4
14+
with:
15+
# We need the full history below.
16+
fetch-depth: 0
1017

1118
- name: Update rustup
1219
run: rustup self update
@@ -23,6 +30,10 @@ jobs:
2330
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
2431
echo "$(pwd)/bin" >> ${GITHUB_PATH}
2532
33+
- name: Install mdbook-i18n-helpers
34+
run: |
35+
cargo install mdbook-i18n-helpers --locked --version 0.3.0
36+
2637
- name: Report versions
2738
run: |
2839
rustup --version
@@ -41,6 +52,28 @@ jobs:
4152
https://raw.githubusercontent.com/rust-lang/rust/master/src/tools/linkchecker/linkcheck.sh
4253
sh linkcheck.sh --all rust-by-example
4354
55+
- name: Build all translations
56+
run: |
57+
for po_lang in ${{ env.LANGUAGES }}; do
58+
POT_CREATION_DATE=$(grep --max-count 1 '^"POT-Creation-Date:' po/$po_lang.po | sed -E 's/".*: (.*)\\n"/\1/')
59+
if [[ $POT_CREATION_DATE == "" ]]; then
60+
POT_CREATION_DATE=now
61+
fi
62+
63+
echo "::group::Building $po_lang translation as of $POT_CREATION_DATE"
64+
rm -r src/
65+
git restore --source "$(git rev-list -n 1 --before "$POT_CREATION_DATE" @)" src/
66+
67+
# Set language and adjust site URL. Clear the redirects
68+
# since they are in sync with the source files, not the
69+
# translation.
70+
MDBOOK_BOOK__LANGUAGE=$po_lang \
71+
MDBOOK_OUTPUT__HTML__SITE_URL=/rust-by-example/$po_lang/ \
72+
MDBOOK_OUTPUT__HTML__REDIRECT='{}' \
73+
mdbook build -d book/$po_lang
74+
echo "::endgroup::"
75+
done
76+
4477
- name: Upload Artifact
4578
uses: actions/upload-artifact@v3
4679
with:

‎.gitignore

+3-1
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,6 @@
11
book
22

3+
po/messages.pot
4+
35
# Auto-generated files from macOS
4-
.DS_Store
6+
.DS_Store

‎README.md

+25
Original file line numberDiff line numberDiff line change
@@ -27,12 +27,37 @@ mdbook serve
2727
To be able to run the examples, you must be connected to the internet; you can
2828
read all content offline, however!
2929

30+
The following warnings can be ignored safely.
31+
32+
```
33+
[WARN] (mdbook::preprocess::cmd): The command wasn't found, is the "gettext" preprocessor installed?
34+
[WARN] (mdbook::preprocess::cmd): Command: mdbook-gettext
35+
```
36+
37+
### Using translated version
38+
39+
If there is a translated resource in `po/` directory, it can be specified through `MDBOOK_BOOK__LANGUAGE` like below:
40+
41+
```bash
42+
git clone https://github.com/rust-lang/rust-by-example
43+
cd rust-by-example
44+
cargo install mdbook
45+
MDBOOK_BOOK__LANGUAGE=ja mdbook build
46+
MDBOOK_BOOK__LANGUAGE=ja mdbook serve
47+
```
48+
3049
## Contributing
3150

3251
Please see the [CONTRIBUTING.md] file for more details.
3352

3453
[CONTRIBUTING.md]: https://github.com/rust-lang/rust-by-example/blob/master/CONTRIBUTING.md
3554

55+
## Translating
56+
57+
Please see the [TRANSLATING.md] file for more details.
58+
59+
[TRANSLATING.md]: https://github.com/rust-lang/rust-by-example/blob/master/TRANSLATING.md
60+
3661
## Translations to other languages
3762

3863
* [Bulgarian](https://github.com/kberov/rust-by-example-bg)

‎TRANSLATING.md

+85
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,85 @@
1+
# Rust by Example 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/rust-by-example/blob/master/CONTRIBUTING.md
7+
8+
## Translation workflow
9+
10+
### Preparation
11+
12+
RBE 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/rbe.yml` and `theme/index.hbs` like below:
59+
60+
* `rbe.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+
```

‎book.toml

+9
Original file line numberDiff line numberDiff line change
@@ -13,6 +13,15 @@ enable = true
1313

1414
[output.html]
1515
git-repository-url = "https://github.com/rust-lang/rust-by-example"
16+
additional-css = [
17+
"theme/css/language-picker.css",
18+
]
1619

1720
[rust]
1821
edition = "2021"
22+
23+
[build]
24+
extra-watch-dirs = ["po"]
25+
26+
[preprocessor.gettext]
27+
after = ["links"]

‎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+
}

0 commit comments

Comments
 (0)