Set up language fallback for docs, and update translation guidelines (q…

…mk#7403)

* Set up language fallback for docs, and update translation guidelines

* Title Case

* Add ID example

* Link to emoji flag cheatsheet

* Move docs preview section to contributing.md

* Point to docs preview in the readme

docs/_summary.md

@@ -111,7 +111,7 @@
  * [Using Eclipse with QMK](other_eclipse.md)
  * [Using VSCode with QMK](other_vscode.md)
  * [Support](support.md)
- * [How to add translations](translating.md)
+ * [Translating the QMK Docs](translating.md)
 
 * QMK Internals (In Progress)
  * [Defines](internals_defines.md)

docs/contributing.md

@@ -101,6 +101,18 @@ enum my_keycodes {
 };
 ```
 
+### Previewing the Documentation
+
+Before opening a pull request, you can preview your changes if you have set up the development environment by running this command from the `qmk_firmware/` folder:
+
+ ./bin/qmk docs
+
+or if you only have Python 3 installed:
+
+ python3 -m http.server 8936
+
+and navigating to `https://localhost:8936/`.
+
 ## Keymaps
 
 Most first-time QMK contributors start with their personal keymaps. We try to keep keymap standards pretty casual (keymaps, after all, reflect the personality of their creators) but we do ask that you follow these guidelines to make it easier for others to discover and learn from your keymap.

docs/index.html

@@ -35,6 +35,15 @@
  loadNavbar: '_langs.md',
  mergeNavbar: true,
  auto2top: true,
+ fallbackLanguages: [
+ 'de',
+ 'es',
+ 'fr-fr',
+ 'he-il',
+ 'ja',
+ 'ru-ru',
+ 'zh-cn'
+ ],
  formatUpdated: '{YYYY}/{MM}/{DD} {HH}:{mm}',
  search: {
  paths: 'auto',

docs/translating.md

@@ -1,29 +1,49 @@
-# How to translate the QMK docs into different languages
+# Translating the QMK Docs
 
 All files in the root folder (`docs/`) should be in English - all other languages should be in subfolders with the ISO 639-1 language codes, followed by `-` and the country code where relevant. [A list of common ones can be found here](https://www.andiamo.co.uk/resources/iso-language-codes/). If this folder doesn't exist, you may create it. Each of the translated files should have the same name as the English version, so things can fall back successfully.
 
 A `_summary.md` file should exist in this folder with a list of links to each file, with a translated name, and link preceded by the language folder:
 
- * [QMK简介](zh-cn/getting_started_introduction.md)
+```markdown
+ * [QMK简介](zh-cn/getting_started_introduction.md)
+```
+
+All links to other docs pages must also be prefixed with the language folder. If the link is to a specific part of the page (ie. a certain heading), you must use the English ID for the heading, like so:
+
+```markdown
+[建立你的环境](zh-cn/newbs-getting-started.md#set-up-your-environment)
+
+## 建立你的环境 :id=set-up-your-environment
+```
 
 Once you've finished translating a new language, you'll also need to modify the following files:
 
 * [`docs/_langs.md`](https://github.com/qmk/qmk_firmware/blob/master/docs/_langs.md) 
- Each line should contain a country flag in the format `:us:` followed by the name represented in its own language: 
-
- - [:cn: 中文](/zh-cn/)
+ Each line should contain a country flag as a [GitHub emoji shortcode](https://github.com/ikatyang/emoji-cheat-sheet/blob/master/README.md#country-flag) followed by the name represented in its own language:
+
+ ```markdown
+ - [:cn: 中文](/zh-cn/)
+ ```
 
 * [`docs/index.html`](https://github.com/qmk/qmk_firmware/blob/master/docs/index.html) 
- Both `placeholder` and `noData` objects should have a dictionary entry for the language folder in a string: 
-
- '/zh-cn/': '没有结果!',
+ Both `placeholder` and `noData` objects should have a dictionary entry for the language folder in a string:
+
+ ```js
+ '/zh-cn/': '没有结果!',
+ ```
 
-## Previewing the translations
+ And make sure to add the language folder in the `fallbackLanguages` list, so it will properly fall back to English instead of 404ing:
 
-Before opening a pull request, you can preview your additions if you have Python 3 installed by running this command in the `docs/` folder:
+ ```js
+ fallbackLanguages: [
+ // ...
+ 'zh-cn',
+ // ...
+ ],
+ ```
 
- python -m http.server 9000
+## Previewing the Translations
 
-and navigating to https://localhost:9000/ - you should be able to select your new language from the "Translations" menu at the top-right.
+See (Previewing the Documentation)[contributing.md#previewing-the-documentation] for how to set up a local instance of the docs - you should be able to select your new language from the "Translations" menu at the top-right.
 
 Once you're happy with your work, feel free to open a pull request!

readme.md

@@ -13,7 +13,9 @@ This is a keyboard firmware based on the [tmk\_keyboard firmware](https://github
 
 * [See the official documentation on docs.qmk.fm](https://docs.qmk.fm)
 
-The docs are powered by [Docsify](https://docsify.js.org/) and hosted on [GitHub](/docs/). You can request changes by making a fork and [pull request](https://github.com/qmk/qmk_firmware/pulls), or by clicking the "Edit Document" link at the bottom of any page.
+The docs are powered by [Docsify](https://docsify.js.org/) and hosted on [GitHub](/docs/). They are also viewable offline; see [Previewing the Documentation](https://docs.qmk.fm/#/contributing?id=previewing-the-documentation) for more details.
+
+You can request changes by making a fork and opening a [pull request](https://github.com/qmk/qmk_firmware/pulls), or by clicking the "Edit Document" link at the bottom of any page.
 
 ## Supported Keyboards