Skip to content

Commit

Permalink
chore: add translation guide into contributing.md
Browse files Browse the repository at this point in the history
  • Loading branch information
Jinjiang committed Apr 5, 2023
1 parent 6dff18f commit 3b14a11
Showing 1 changed file with 30 additions and 0 deletions.
30 changes: 30 additions & 0 deletions .github/contributing.md
Expand Up @@ -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 has a English version by default, and translation(s) in corresponding `<lang>` sub-folder(s):

- `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 to translate 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!
Expand Down

0 comments on commit 3b14a11

Please sign in to comment.