Vue Community Translation Guidelines

If you are here, you are likely interested in contributing to the translation of the Vue.js documentation. Thank you! Before you start, make sure to read the following guidelines to get an understanding of the workflow.

For translating docs of more Vue ecosystem projects, see Vue Ecosystem Translation Guidelines.

High Level Steps of Working on a New Translation

Open a thread in the Discussion tab to indicate your intention of working on a translation. Make sure to check if there is already one created for your language - this can help avoid duplicated efforts. Use the thread to find fellow collaborators to form a translation team. We strongly suggest working as a team because peer reviews are necessary to ensure translation quality.
Fork vuejs/docs to start the translation process in your own repo (you can create a dedicated organization for it if you want). Make sure to read the Workflow Recommendations section below before you start! Feel free to deploy your own preview with Vercel or Netlify during this phase.
Send us a Pull Request to add your WIP repo to the end of this README file.
Once you have completed translation for more than 50% of the content, you can ping us in the original discussion thread to request officially transferring the repo into the vuejs-translations organization. We will invite you and other collaborators to the organization so you can continue working on it.

We will also create an official deployment with *.vuejs.org URL (we have partnerships with hosting platforms so you don't need to bear the cost in case the traffic gets high).

Some Notes:
- Before performing the transfer, use the GitHub support request to detach your fork. This is necessary because GitHub doesn't allow multiple forks of the same source repo to co-exist in the same organization.
- When you first transfer the repo, you likely won't have write access to it because the repo will need to be assigned to the team for proper permissions, let us know once the transfer is done so we can set it up.
- For consistency, the team and repo names are determined based on the ISO 639-1 language codes.
Once translation is finished, Send us a Pull Request to add a link to the translation on vuejs.org. See example 1 and example 2. We will merge it and announce the translation from the official Twitter account!

Workflow Recommendations

Setup

Read the Contributing Section of the English docs. Make sure to use pnpm and Node.js v14+. Familiarize yourself with VitePress' markdown extension features.

Use Issues and Pull Requests

It's recommended to manage the workload using issues and pull requests. Create an issue for each page that still needs translation, then let team members self-assign to claim the work. Create a pull request for the translation of each page. This way, other collaborators can review and provide feedback before the the PR is merged. It is also recommended to use "Squash and Merge" for the PRs so you have a clean history.

Document Translation Conventions

When working as a team, make sure to use consistent translations for common terminologies to avoid confusion. It's best to have a place to document the conventions and consensus generated from reviews. You can use GitHub wiki, team discussions thread, or directly as a markdown file in the repo itself. If a term is particularly tricky to concisely translate in your language, consider leaving it untranslated.

Translating Non-Content Text

Some text are part of the VitePress theme instead of markdown content. You can translate these in .vitepress/config.ts. In addition to navigation and sidebar items, you can also customize most of the theme text by providing the themeConfig.i18n option. Example usage in Chinese translation

Translating Images

All the images are embeded into docs with the Figma URLs set aside as code comments. You can search them out by this link:

https://github.com/search?q=repo%3Avuejs%2Fdocs%20figma&type=code

To translate the text in those images, we recommend to:

fork the Figma docs accordingly,
translate the text in Figma, and
export the new image.

You can add specific suffixes to the new images according to your language code. Adding the forked Figma URL in the code comment is also welcome. Example practice in Chinese translation

Retaining Original Anchors

VitePress automatically generates header anchor links (links that start with #) based on the text. Since we have a lot of cross-linking to headers within the site, it is easier to retain original English header links so that you don't need to update links everywhere when you translate the headers. It also makes it easier to switch between different languages of the same header link.

We already added header anchor links in the original English document, use the following syntax when translating to retain them:

- ## Original Header {#original-header}
+ ## Translated Header {#original-header}

You may also notice that some headers are followed by one or two \* markers:

### `<script setup>` \*\* {#script-setup}

These are custom markers we use to differentiate between Options-API-only and Composition-API-only sections. We use a custom markdown plugin to wrap these sections in additional divs that can be shown / hidden by toggling CSS classes. Please keep them when translating the headers!

Syncing with Upstream

It is recommended to set up an automated workflow to sync with upstream updates from time to time. If you don't have an existing preferred method of doing so, we have two recommendations:

Use Ryu-Cho to track upstream updates and automatically open issue / PRs. See example workflow in Japanese translation.
Create an upstream branch, and use this GitHub Action to sync that branch with the English docs. Periodically create PRs between upstream and main to sync the content with necessary translations. See example config in Chinese translation.

You can reach out to the respective teams in their translations repo if you have questions on how to set up syncing.

mostafa-nematpour/guidelines