From 9ea9806d67dd3dfd775cf854b9becd35f3cdc748 Mon Sep 17 00:00:00 2001 From: fauxpark Date: Sun, 24 Nov 2019 03:07:15 +1100 Subject: [PATCH] Set up language fallback for docs, and update translation guidelines (#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 | 2 +- docs/contributing.md | 12 ++++++++++++ docs/index.html | 9 +++++++++ docs/translating.md | 44 ++++++++++++++++++++++++++++++++------------ readme.md | 4 +++- 5 files changed, 57 insertions(+), 14 deletions(-) diff --git a/docs/_summary.md b/docs/_summary.md index 808a8de4a0a..409df6d18f1 100644 --- a/docs/_summary.md +++ b/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) diff --git a/docs/contributing.md b/docs/contributing.md index 04dc0da20fd..7c365b41863 100644 --- a/docs/contributing.md +++ b/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 `http://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. diff --git a/docs/index.html b/docs/index.html index d2ba99897c7..d20fbd64a00 100644 --- a/docs/index.html +++ b/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', diff --git a/docs/translating.md b/docs/translating.md index 6eb268763a0..12fe7c85f8a 100644 --- a/docs/translating.md +++ b/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 http://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! diff --git a/readme.md b/readme.md index 2641e2c2ef8..5a9166c0442 100644 --- a/readme.md +++ b/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