rust-lang · Ruin0x11 · Aug 27, 2020 · Aug 27, 2020 · Aug 27, 2020 · Aug 28, 2020
diff --git a/.gitignore b/.gitignore
@@ -8,6 +8,7 @@ guide/book
 
 .vscode
 tests/dummy_book/book/
+tests/localized_book/book/
 test_book/book/
 
 # Ignore Jetbrains specific files.

diff --git a/Cargo.lock b/Cargo.lock
diff --git a/Cargo.toml b/Cargo.toml
@@ -21,6 +21,7 @@ chrono = "0.4"
 clap = "2.24"
 env_logger = "0.7.1"
 handlebars = "4.0"
+http = "0.2.4"
 lazy_static = "1.0"
 log = "0.4"
 memchr = "2.0"

diff --git a/guide/book.toml b/guide/book.toml
@@ -28,3 +28,6 @@ heading-split-level = 2
 
 [output.html.redirect]
 "/format/config.html" = "configuration/index.html"
+
+[language.en]
+name = "English"
diff --git a/guide/src/404.md → guide/src/en/404.md b/guide/src/404.md → guide/src/en/404.md
diff --git a/guide/src/README.md → guide/src/en/README.md b/guide/src/README.md → guide/src/en/README.md
diff --git a/guide/src/SUMMARY.md → guide/src/en/SUMMARY.md b/guide/src/SUMMARY.md → guide/src/en/SUMMARY.md
@@ -25,6 +25,7 @@
         - [General](format/configuration/general.md)
         - [Preprocessors](format/configuration/preprocessors.md)
         - [Renderers](format/configuration/renderers.md)
+        - [Localization](format/configuration/localization.md)
         - [Environment Variables](format/configuration/environment-variables.md)
     - [Theme](format/theme/README.md)
         - [index.hbs](format/theme/index-hbs.md)

diff --git a/guide/src/cli/README.md → guide/src/en/cli/README.md b/guide/src/cli/README.md → guide/src/en/cli/README.md
diff --git a/guide/src/cli/build.md → guide/src/en/cli/build.md b/guide/src/cli/build.md → guide/src/en/cli/build.md
diff --git a/guide/src/cli/clean.md → guide/src/en/cli/clean.md b/guide/src/cli/clean.md → guide/src/en/cli/clean.md
diff --git a/guide/src/cli/completions.md → guide/src/en/cli/completions.md b/guide/src/cli/completions.md → guide/src/en/cli/completions.md
diff --git a/guide/src/cli/init.md → guide/src/en/cli/init.md b/guide/src/cli/init.md → guide/src/en/cli/init.md
@@ -14,13 +14,19 @@ up for you:
 ```bash
 book-test/
 ├── book
+├── book.toml
 └── src
-    ├── chapter_1.md
-    └── SUMMARY.md
+    └── en
+        ├── chapter_1.md
+        └── SUMMARY.md
 ```
 
-- The `src` directory is where you write your book in markdown. It contains all
-  the source files, configuration files, etc.
+- The `src` directory is where you write your book in Markdown. It contains all
+  the source files for each translation of your book. By default, a directory
+  for the English translation is created, `src/en`.
+
+- The `book.toml` file holds configuration about how your book gets rendered.
+  See the [configuration](../format/config.md) section for more details.
 
 - The `book` directory is where your book is rendered. All the output is ready
   to be uploaded to a server to be seen by your audience.

diff --git a/guide/src/cli/serve.md → guide/src/en/cli/serve.md b/guide/src/cli/serve.md → guide/src/en/cli/serve.md
diff --git a/guide/src/cli/test.md → guide/src/en/cli/test.md b/guide/src/cli/test.md → guide/src/en/cli/test.md
diff --git a/guide/src/cli/watch.md → guide/src/en/cli/watch.md b/guide/src/cli/watch.md → guide/src/en/cli/watch.md
diff --git a/guide/src/continuous-integration.md → guide/src/en/continuous-integration.md b/guide/src/continuous-integration.md → guide/src/en/continuous-integration.md
diff --git a/guide/src/for_developers/README.md → guide/src/en/for_developers/README.md b/guide/src/for_developers/README.md → guide/src/en/for_developers/README.md
diff --git a/guide/src/for_developers/backends.md → guide/src/en/for_developers/backends.md b/guide/src/for_developers/backends.md → guide/src/en/for_developers/backends.md
diff --git a/...or_developers/mdbook-wordcount/Cargo.toml → ...or_developers/mdbook-wordcount/Cargo.toml b/...or_developers/mdbook-wordcount/Cargo.toml → ...or_developers/mdbook-wordcount/Cargo.toml
diff --git a/...r_developers/mdbook-wordcount/src/main.rs → ...r_developers/mdbook-wordcount/src/main.rs b/...r_developers/mdbook-wordcount/src/main.rs → ...r_developers/mdbook-wordcount/src/main.rs
diff --git a/guide/src/for_developers/preprocessors.md → guide/src/en/for_developers/preprocessors.md b/guide/src/for_developers/preprocessors.md → guide/src/en/for_developers/preprocessors.md
@@ -39,7 +39,7 @@ be adapted for other preprocessors.
 ```rust
 // nop-preprocessors.rs
 
-{{#include ../../../examples/nop-preprocessor.rs}}
+{{#include ../../../../examples/nop-preprocessor.rs}}
 ```
 </details>
 

diff --git a/guide/src/format/README.md → guide/src/en/format/README.md b/guide/src/format/README.md → guide/src/en/format/README.md
diff --git a/guide/src/format/configuration/README.md → guide/src/en/format/configuration/README.md b/guide/src/format/configuration/README.md → guide/src/en/format/configuration/README.md
@@ -4,9 +4,11 @@ This section details the configuration options available in the ***book.toml***:
 - **[General]** configuration including the `book`, `rust`, `build` sections
 - **[Preprocessor]** configuration for default and custom book preprocessors
 - **[Renderer]** configuration for the HTML, Markdown and custom renderers
+- **[Localization]** configuration for books written in more than one language
 - **[Environment Variable]** configuration for overriding configuration options in your environment
 
 [General]: general.md
 [Preprocessor]: preprocessors.md
 [Renderer]: renderers.md
-[Environment Variable]: environment-variables.md
+[Localization]: localization.md
+[Environment Variable]: environment-variables.md
diff --git a/...at/configuration/environment-variables.md → ...at/configuration/environment-variables.md b/...at/configuration/environment-variables.md → ...at/configuration/environment-variables.md
diff --git a/guide/src/format/configuration/general.md → guide/src/en/format/configuration/general.md b/guide/src/format/configuration/general.md → guide/src/en/format/configuration/general.md
diff --git a/guide/src/en/format/configuration/localization.md b/guide/src/en/format/configuration/localization.md
@@ -0,0 +1,86 @@
+# Localization
+
+It's possible to write your book in more than one language and bundle all of its
+translations into a single output folder, with the ability for readers to switch
+between each one in the rendered output. The available languages for your book
+are defined in the `[language]` table:
+
+```toml
+[language.en]
+name = "English"
+
+[language.ja]
+name = "日本語"
+title = "本のサンプル"
+description = "この本は実例です。"
+authors = ["Ruin0x11"]
+```
+
+Each language must have a human-readable `name` defined. Also, if the
+`[language]` table is defined, you must define `book.language` to be a key of
+this table, which will indicate the language whose files will be used for
+fallbacks if a page is missing in a translation.
+
+The `title` and `description` fields, if defined, will override the ones set in
+the `[book]` section. This way you can translate the book's title and
+description. `authors` provides a list of this translation's authors.
+
+After defining a new language like `[language.ja]`, add a new subdirectory
+`src/ja` and create your `SUMMARY.md` and other files there.
+
+> **Note:** Whether or not the `[language]` table is defined changes the format
+> of the `src` directory that mdBook expects to see. If there is no `[language]`
+> table, mdBook will treat the `src` directory as a single translation of the
+> book, with `SUMMARY.md` at the root:
+>
+> ```
+> ├── book.toml
+> └── src
+>     ├── chapter
+>     │   ├── 1.md
+>     │   ├── 2.md
+>     │   └── README.md
+>     ├── README.md
+>     └── SUMMARY.md
+> ```
+> 
+> If the `[language]` table is defined, mdBook will instead expect to find
+> subdirectories under `src` named after the keys in the table:
+>
+> ```
+> ├── book.toml
+> └── src
+>     ├── en
+>     │   ├── chapter
+>     │   │   ├── 1.md
+>     │   │   ├── 2.md
+>     │   │   └── README.md
+>     │   ├── README.md
+>     │   └── SUMMARY.md
+>     └── ja
+>         ├── chapter
+>         │   ├── 1.md
+>         │   ├── 2.md
+>         │   └── README.md
+>         ├── README.md
+>         └── SUMMARY.md
+> ```
+
+If the `[language]` table is used, you can pass the `-l <language id>` argument
+to commands like `mdbook build` to build the book for only a single language. In
+this example, `<language id>` can be `en` or `ja`.
+
+Some extra notes on translations:
+
+- In a translation's `SUMMARY.md` or inside Markdown files, you can link to
+  pages, images or other files that don't exist in the current translation, but
+  do exist in the default translation. This is so you can have a fallback in
+  case new pages get added in the default language that haven't been translated
+  yet.
+- Each translation can have its own `SUMMARY.md` with differing content from
+  other translations. Even if the translation's summary goes out of sync with
+  the default language, the links will continue to work so long as the pages
+  exist in either translation.
+- Each translation can have its own pages listed in `SUMMARY.md` that don't
+  exist in the default translation at all, in case extra information specific to
+  that language is needed.
diff --git a/...src/format/configuration/preprocessors.md → .../en/format/configuration/preprocessors.md b/...src/format/configuration/preprocessors.md → .../en/format/configuration/preprocessors.md
diff --git a/guide/src/format/configuration/renderers.md → .../src/en/format/configuration/renderers.md b/guide/src/format/configuration/renderers.md → .../src/en/format/configuration/renderers.md
diff --git a/guide/src/format/example.rs → guide/src/en/format/example.rs b/guide/src/format/example.rs → guide/src/en/format/example.rs
diff --git a/guide/src/format/images/rust-logo-blk.svg → guide/src/en/format/images/rust-logo-blk.svg b/guide/src/format/images/rust-logo-blk.svg → guide/src/en/format/images/rust-logo-blk.svg
diff --git a/guide/src/format/markdown.md → guide/src/en/format/markdown.md b/guide/src/format/markdown.md → guide/src/en/format/markdown.md
diff --git a/guide/src/format/mathjax.md → guide/src/en/format/mathjax.md b/guide/src/format/mathjax.md → guide/src/en/format/mathjax.md
diff --git a/guide/src/format/mdbook.md → guide/src/en/format/mdbook.md b/guide/src/format/mdbook.md → guide/src/en/format/mdbook.md
diff --git a/guide/src/format/summary.md → guide/src/en/format/summary.md b/guide/src/format/summary.md → guide/src/en/format/summary.md
diff --git a/guide/src/format/theme/README.md → guide/src/en/format/theme/README.md b/guide/src/format/theme/README.md → guide/src/en/format/theme/README.md
diff --git a/guide/src/format/theme/editor.md → guide/src/en/format/theme/editor.md b/guide/src/format/theme/editor.md → guide/src/en/format/theme/editor.md
diff --git a/guide/src/format/theme/index-hbs.md → guide/src/en/format/theme/index-hbs.md b/guide/src/format/theme/index-hbs.md → guide/src/en/format/theme/index-hbs.md
diff --git a/...e/src/format/theme/syntax-highlighting.md → ...rc/en/format/theme/syntax-highlighting.md b/...e/src/format/theme/syntax-highlighting.md → ...rc/en/format/theme/syntax-highlighting.md
diff --git a/guide/src/misc/contributors.md → guide/src/en/misc/contributors.md b/guide/src/misc/contributors.md → guide/src/en/misc/contributors.md
@@ -20,5 +20,6 @@ shout-out to them!
 - Vivek Akupatni ([apatniv](https://github.com/apatniv))
 - Eric Huss ([ehuss](https://github.com/ehuss))
 - Josh Rotenberg ([joshrotenberg](https://github.com/joshrotenberg))
+- [Ruin0x11](https://github.com/Ruin0x11)
 
 If you feel you're missing from this list, feel free to add yourself in a PR.