Skip to content

Commit 4b08a12

Browse files
Jinjiangposva
andauthored
chore: add translation guide into contributing.md (#1778)
Co-authored-by: Eduardo San Martin Morote <posva@users.noreply.github.com>
1 parent cc9f56b commit 4b08a12

File tree

1 file changed

+30
-0
lines changed

1 file changed

+30
-0
lines changed

.github/contributing.md

Lines changed: 30 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -109,6 +109,36 @@ Unit tests are located inside `__tests__`. Consult the [Jest docs](https://jestj
109109
- Write a unit test whenever possible
110110
- If a test is specific to a browser, create an e2e (end to end) test and make sure to indicate it on the test
111111

112+
## Contributing Docs
113+
114+
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):
115+
116+
- [`zh`](https://github.com/vuejs/router/tree/main/packages/docs/zh): Chinese translation.
117+
118+
Besides that, the `.vitepress` sub-folder is used to put the config and theme, including the i18n information.
119+
120+
If you want to start translating the docs in a new language:
121+
122+
1. Create the corresponding `<lang>` sub-folder for your translation.
123+
2. Modify the i18n config in `.vitepress` sub-folder.
124+
3. Translate the docs and run the doc site to self-test locally.
125+
4. Once you have done all above, create a pull request to our GitHub repo.
126+
127+
If you want to maintain a existing translation:
128+
129+
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:
130+
- 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.
131+
- 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.
132+
2. See what translation you need to do to sync up with the original docs. There are 2 popular ways:
133+
- Git diff command: e.g. `git diff docs-sync-zh..main packages/docs # > debug.log`, or
134+
- GitHub Compare page: e.g. https://github.com/vuejs/router/compare/docs-sync-zh...main (only see the changes in `packages/docs/*`)
135+
3. Create your own branch and start the translation update, following the diff or compare.
136+
4. Once you have done all above, create a pull request to our GitHub repo.
137+
- 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`.
138+
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`.
139+
140+
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).
141+
112142
## Credits
113143

114144
Thank you to all the people who have already contributed to Vue Router!

0 commit comments

Comments
 (0)