Skip to content

Commit 2060131

Browse files
mgeislermgeisler
authored
Merge pull request #130 from google/translations
Add support for translations
2 parents 8e3941d + f42c76e commit 2060131

File tree

11 files changed

+14606
-33
lines changed

11 files changed

+14606
-33
lines changed

‎.github/workflows/build.yml

+84
Original file line numberDiff line numberDiff line change
@@ -39,3 +39,87 @@ jobs:
3939

4040
- name: Test Rust code
4141
run: cargo test
42+
43+
- name: Test i18n-helpers
44+
run: cargo test
45+
working-directory: i18n-helpers
46+
47+
i18n-helpers:
48+
runs-on: ubuntu-latest
49+
steps:
50+
- name: Checkout
51+
uses: actions/checkout@v3
52+
53+
- name: Setup Rust cache
54+
uses: Swatinem/rust-cache@v2
55+
56+
- name: Install Gettext
57+
run: sudo apt install gettext
58+
59+
- name: Install mdbook
60+
run: cargo install mdbook --version 0.4.25
61+
62+
- name: Install mdbook-svgbob
63+
run: cargo install mdbook-svgbob --version 0.2.1
64+
65+
- name: Install i18n-helpers
66+
run: cargo install --path i18n-helpers --locked
67+
68+
- name: Generate po/messages.pot
69+
run: mdbook build -d po
70+
env:
71+
MDBOOK_OUTPUT: '{"xgettext": {"pot-file": "messages.pot"}}'
72+
73+
- name: Test messages.pot
74+
run: msgfmt --statistics -o /dev/null po/messages.pot
75+
76+
- name: Expand includes without translation
77+
run: mdbook build -d expanded
78+
env:
79+
MDBOOK_OUTPUT: '{"markdown": {}}'
80+
81+
- name: Expand includes with no-op translation
82+
run: mdbook build -d no-op
83+
env:
84+
MDBOOK_OUTPUT: '{"markdown": {}}'
85+
MDBOOK_PREPROCESSOR__GETTEXT__PO_FILE: po/messages.pot
86+
87+
- name: Compare no translation to no-op translation
88+
run: diff -r expanded no-op
89+
90+
translations:
91+
runs-on: ubuntu-latest
92+
strategy:
93+
matrix:
94+
language:
95+
- da
96+
env:
97+
MDBOOK_BOOK__LANGUAGE: ${{ matrix.language }}
98+
MDBOOK_PREPROCESSOR__GETTEXT__PO_FILE: po/${{ matrix.language }}.po
99+
steps:
100+
- name: Checkout
101+
uses: actions/checkout@v3
102+
103+
- name: Setup Rust cache
104+
uses: Swatinem/rust-cache@v2
105+
106+
- name: Install Gettext
107+
run: sudo apt install gettext
108+
109+
- name: Install mdbook
110+
run: cargo install mdbook --version 0.4.25
111+
112+
- name: Install mdbook-svgbob
113+
run: cargo install mdbook-svgbob --version 0.2.1
114+
115+
- name: Install i18n-helpers
116+
run: cargo install --path i18n-helpers --locked
117+
118+
- name: Test ${{ matrix.language }} translation
119+
run: msgfmt --statistics -o /dev/null po/${{ matrix.language }}.po
120+
121+
- name: Build course with ${{ matrix.language }} translation
122+
run: mdbook build
123+
124+
- name: Test code snippets with ${{ matrix.language }} translation
125+
run: mdbook test

‎.gitignore

+2-1
Original file line numberDiff line numberDiff line change
@@ -1,2 +1,3 @@
11
/book/
2-
/target/
2+
target/
3+
po/messages.pot

‎TRANSLATIONS.md

+116
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,116 @@
1+
# Translations of Comprehensive Rust 🦀
2+
3+
We would love to have your help with translating the course into other
4+
languages! We use the [Gettext] system for translations. This means that you
5+
don't modify the Markdown files directly: instead you modify `.po` files in a
6+
`po/` directory. The `.po` files are small text-based translation databases.
7+
8+
There is a `.po` file for each language. They are named after the [ISO 639]
9+
language codes: Danish would go into `po/da.po`, Korean would go into
10+
`po/ko.po`, etc. The `.po` files contain all the English text plus the
11+
translations. They are initialized from a `messages.pot` file (a PO template)
12+
which contains only the English text.
13+
14+
We will show how to update and manipulate the `.po` and `.pot` files using the
15+
GNU Gettext utilities below.
16+
17+
[Gettext]: https://www.gnu.org/software/gettext/manual/html_node/index.html
18+
[ISO 639]: https://en.wikipedia.org/wiki/List_of_ISO_639-1_codes
19+
20+
## I18n Helpers
21+
22+
We use two helpers for the translations:
23+
24+
* `mdbook-xgettext`: This program extracts the English text. It is an mdbook
25+
renderer.
26+
* `mdbook-gettext`: This program translates the book into a target language. It
27+
is an mdbook preprocessor.
28+
29+
Install both helpers with the following command from the root of the course:
30+
31+
```shell
32+
$ cargo install --path i18n-helpers
33+
```
34+
35+
## Creating and Updating Translations
36+
37+
First, you need to know how to update the `.pot` and `.po` files.
38+
39+
As a general rule, you should never touch the auto-generated `po/messages.pot`
40+
file. You should also not edit the `msgid` entries in a `po/xx.po` file. If you
41+
find mistakes, you need to update the original English text instead. The fixes
42+
to the English text will flow into the `.po` files the next time the translators
43+
update them.
44+
45+
### Generating the PO Template
46+
47+
To extract the original English text and generate a `messages.pot` file, you run
48+
`mdbook` with a special renderer:
49+
50+
```shell
51+
$ MDBOOK_OUTPUT='{"xgettext": {"pot-file": "messages.pot"}}' \
52+
mdbook build -d po
53+
```
54+
55+
You will find the generated POT file as `po/messages.pot`.
56+
57+
### Initialize a New Translation
58+
59+
To start a new translation, first generate the `po/messages.pot` file. Then use
60+
`msginit` to create a `xx.po` file for the fictional `xx` language:
61+
62+
```shell
63+
$ msginit -i po/messages.pot -l xx -o po/xx.po
64+
```
65+
66+
You can also simply copy `po/messages.pot` to `po/xx.po`. Then update the file
67+
header (the first entry with `msgid ""`) to the correct language.
68+
69+
### Updating an Existing Translation
70+
71+
As the English text changes, translations gradually become outdated. To update
72+
the `po/xx.po` file with new messages, first extract the English text into a
73+
`po/messages.pot` template file. Then run
74+
75+
```shell
76+
$ msgmerge --update po/xx.po po/messages.pot
77+
```
78+
79+
Unchanged messages will stay intact, deleted messages are marked as old, and
80+
updated messages are marked "fuzzy". A fuzzy entry will reuse the previous
81+
translation: you should then go over it and update it as necessary before you
82+
remove the fuzzy marker.
83+
84+
## Using Translations
85+
86+
This will show you how to use the translations to generate localized HTML
87+
output.
88+
89+
## Building a Translation
90+
91+
To use the `po/xx.po` file for your output, run the following command:
92+
93+
```shell
94+
$ MDBOOK_BOOK__LANGUAGE='xx' \
95+
MDBOOK_PREPROCESSOR__GETTEXT__PO_FILE='po/xx.po' \
96+
MDBOOK_PREPROCESSOR__GETTEXT__RENDERERS='["html"]' \
97+
MDBOOK_PREPROCESSOR__GETTEXT__BEFORE='["svgbob"]' \
98+
mdbook build -d book/xx
99+
```
100+
101+
This will update the book's language to `xx`, it will make the `mdbook-gettext`
102+
preprocessor become active and tell it to use the `po/xx.po` file, and finally
103+
it will redirect the output to `book/xx`.
104+
105+
## Serving a Translation
106+
107+
Like normal, you can use `mdbook serve` to view your translation as you work on
108+
it. You use the same command as with `mdbook build` above, but additionally
109+
we'll tell `mdbook` to watch the `po/` directory for changes:
110+
111+
```shell
112+
$ MDBOOK_BOOK__LANGUAGE=xx \
113+
MDBOOK_PREPROCESSOR__GETTEXT__PO_FILE=po/xx.po
114+
MDBOOK_BUILD__EXTRA_WATCH_DIRS='["po"]'
115+
mdbook serve -d book/xx
116+
```

‎book.toml

+7
Original file line numberDiff line numberDiff line change
@@ -8,7 +8,14 @@ title = "Comprehensive Rust 🦀"
88
[rust]
99
edition = "2021"
1010

11+
[preprocessor.links]
12+
renderers = ["html"]
13+
14+
[preprocessor.index]
15+
renderers = ["html"]
16+
1117
[preprocessor.svgbob]
18+
renderers = ["html"]
1219
class = "bob"
1320

1421
[output.html]

0 commit comments

Comments
 (0)