chore: add translation guide into contributing.md (#1778)

Co-authored-by: Eduardo San Martin Morote <posva@users.noreply.github.com>

diff --git a/.github/contributing.md b/.github/contributing.md
index b4f277969ac5d21c78177b0f85790b03cd0ecce1..89a1ccd11e418614e212d6f8c8bdde6f2f038d55 100644 (file)
--- a/.github/contributing.md
+++ b/.github/contributing.md
@@ -109,6 +109,36 @@ Unit tests are located inside `__tests__`. Consult the [Jest docs](https://jestj
 - Write a unit test whenever possible
 - If a test is specific to a browser, create an e2e (end to end) test and make sure to indicate it on the test
 
+## Contributing Docs
+
+Currently, all the docs can be found in `packages/docs`. It contains the English markdown files while translation(s) are stored in their corresponding `<lang>` sub-folder(s):
+
+- [`zh`](https://github.com/vuejs/router/tree/main/packages/docs/zh): Chinese translation.
+
+Besides that, the `.vitepress` sub-folder is used to put the config and theme, including the i18n information.
+
+If you want to start translating the docs in a new language:
+
+1. Create the corresponding `<lang>` sub-folder for your translation.
+2. Modify the i18n config in `.vitepress` sub-folder.
+3. Translate the docs and run the doc site to self-test locally.
+4. Once you have done all above, create a pull request to our GitHub repo.
+
+If you want to maintain a existing translation:
+
+1. (Repo permission required) First of all, make sure there is a _checkpoint_ branch for the language. Usually it's named as `docs-sync-<lang>`. Notice that:
+    - This branch is always synced to the commit of the original docs that the latest translation of your language is corresponding to. Like `docs-sync-zh` is always to the commit of the original docs that the latest Chinese translation is corresponding to.
+    - Technically, this checkpoint branch should be only updated if the translation is synced to a nearer commit of the original docs. Usually the commit is the HEAD of the `main` branch at that moment.
+2. See what translation you need to do to sync up with the original docs. There are 2 popular ways:
+         - Git diff command: e.g. `git diff docs-sync-zh..main packages/docs # > debug.log`, or
+         - GitHub Compare page: e.g. https://github.com/vuejs/router/compare/docs-sync-zh...main (only see the changes in `packages/docs/*`)
+3. Create your own branch and start the translation update, following the diff or compare.
+4. Once you have done all above, create a pull request to our GitHub repo.
+    - It's highly recommended to commit with message like `docs(<lang>): sync update to <the-latest-commit>`. e.g. `docs(zh): sync update to e008551`.
+5. (Repo permission required) **VERY IMPORTANT**: after the pull request is merged, for the future batch of sync-up, do another merge from the latest commit at that moment to the checkpoint branch. e.g. merge commit `e008551` to branch `docs-sync-zh`.
+
+For more real examples, please check out [all the PRs with title "docs(zh): sync" after 2023-01-01](https://github.com/vuejs/router/pulls?q=is%3Apr+created%3A%3E2023-01-01+docs%28zh%29+sync).
+
 ## Credits
 
 Thank you to all the people who have already contributed to Vue Router!