Skip to content

Latest commit

 

History

History
81 lines (52 loc) · 4.84 KB

README_ECOSYSTEM.md

File metadata and controls

81 lines (52 loc) · 4.84 KB
Raw

Vue Ecosystem Translation Guidelines

Here are the guidelines for translating docs in Vue ecosystem, including official libraries like Pinia, Vue Router, etc.

Concepts

  1. Language: Every project might have English docs by default. And it's welcome to add docs in other languages. Usually, they are the translations of the English docs.
    • Language List UI: It's a menu list for all the available languages on the doc site. It's helpful for users to switch the docs to their prefered language.
  2. Checkpoint: Since the English docs are keep updating. It's very important for other language docs to have some "checkpoints". A checkpoint is the hash and date of the latest commit when you update the translation. It's crucial for long-term maintenance since all the further translation sync-ups are based on their previous checkpoints.
  3. Translation Status: It's the checkpoints information for all the languages that we have translated.
    • Translation Status UI: It's a block of UI displaying the Translation Status. Usually, it's the date of the latest update for the current language. It's helpful for users to know how fresh the current translation is. Also, it's an invisible encouragement for users to contribute the translations when they find anything outdated.

High Level Steps

If you want to start translating the docs in a new language:

  1. Set up the new language in the repo
  2. Translate all the content into the new language
  3. Initialize the checkpoint information into the Translation Status
  4. Commit all the changes

If you want to keep a translation up-to-date:

  1. Compare the English docs between the latest one and the one on the current language checkpoint.
  2. Create a git branch and update the translation according to the compare result.
  3. Update the current langauge checkpoint.
  4. Commit all the changes

The typical workflow is like this:

typical translation workflow

Some practical advice

Here is some practical advice for the translation. However, when you contribute, please do follow the guidelines of the project for more details.

Usually, the docs of a project is a sub-package based on VitePress in their repo/workspace. So this part is all based on VitePress.

To translate the docs, you have 2 options to follow:

Translate in the official repo

  1. You can add a locale information in the VitePress config.
  2. You can translate all the menu items and navigation items in the new locale of the VitePress config.
  3. You can translate all the i18n info in the new locale of the VitePress config.
  4. The content can be translated and put into a <lang> sub-folder.

In this way above, you will get the translation in the same doc site with:

For better doing that, we have prepared a project named vitepress-translation-helper to help you. See more usage details on its README.

typical translation workflow for regular update

Self-host the translation

  1. You can translate all the menu items and navigation items directly in the VitePress config.
  2. You can translate all the i18n info directly in the VitePress config.
  3. You can translate all the content directly.
  4. You need to self-host your doc site with necessarily config change like the domain, the deployment config, etc.
  5. You are highly encouraged to create a pull request to the official doc site to add a new link to your translation doc site in the Language List UI.

In this way above, you will get the translation in your own host.

For Right-to-Left language

See more information on the VitePress Internationalization page.

Also, in VitePress v1.0.0-rc35 and above, it supports dir field in frontmatter for each page.

Official Vue projects your can translate their docs

Other Vue ecosystem projects

If you have a project would like to show and call for translations, feel free to add it here and create a pull request.