docs: setup translation infra (#2549)

* docs: setup translation infra

* Update netlify.toml

* chore: reuse vitepress-translation-helper for docs

* chore: update the translation guide in contributing doc

* Update CONTRIBUTING.md

.github/CONTRIBUTING.md

@@ -24,3 +24,65 @@ Always try to provide as much information as possible. If you are reporting a bu
 ### Feature requests
 
 Lay out the reasoning behind it and propose an API for it. Ideally, you should have a practical example to prove the utility of the feature you're requesting.
+
+## Contributing Docs
+
+All the documentation files 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/pinia/tree/v2/packages/docs/zh): Chinese translation.
+
+Besides that, the `.vitepress` sub-folder contains the config and theme, including the i18n information.
+
+Contributing to the English docs is the same as contributing to the source code. You can create a pull request to our GitHub repo. However, if you would like to contribute to the translations, there are two options and some extra steps to follow:
+
+### Translate in a `<lang>` sub-folder and host it on our official repo
+
+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 configuration in the `.vitepress` sub-folder.
+3. Translate the docs and run the doc site to self-test locally.
+4. Create a checkpoint for your language by running `pnpm run docs:translation:update <lang> [<commit>]`. A checkpoint is the hash and date of the latest commit when you do the translation. The checkpoint information is stored in the status file `packages/docs/.vitepress/translation-status.json`. _It's crucial for long-term maintenance since all the further translation sync-ups are based on their previous checkpoints._
+5. Commit all the changes and create a pull request to our GitHub repo.
+
+> [!TIP]
+> When you create the checkpoint, please remember to pass the second "commit" argument as `v2` since that's the base branch of Pinia now.
+
+We will have a paragraph at the top of each translation page that shows the translation status. That way, users can quickly determine if the translation is up-to-date or lags behind the English version.
+
+Speaking of the up-to-date translation, we also need good long-term maintenance for every language. If you want to _update_ an existing translation:
+
+1. See what translation you need to sync up with the original docs. There are two popular ways:
+   1. Via the [GitHub Compare](https://github.com/vuejs/pinia/compare/) page, only see the changes in `packages/docs/*` from the checkpoint hash to `v2` branch. You can find the checkpoint hash for your language via the translation status file `packages/docs/.vitepress/translation-status.json`. The compare page can be directly opened with the hash as part of the URL, e.g. https://github.com/vuejs/pinia/compare/c67a5c9...v2
+   2. Via a local command: `pnpm run docs:translation:compare <lang> v2`.
+2. Create your own branch and start the translation update, following the previous comparison.
+3. Create a checkpoint for your language by running `pnpm run docs:translation:update <lang> v2`.
+4. Commit all the changes and create a pull request to our GitHub repo.
+
+<!-- TODO: add an example once we have got one -->
+
+> [!TIP]
+> Before you create the new checkpoint, please remember fetch the latest v2 branch ahead.
+
+### Self-host the translation
+
+You can also host the translation on your own. To create one, fork our GitHub repo and change the content and site config in `packages/docs`. To long-term maintain it, we _highly recommend_ a similar way that we do above for our officially hosted translations:
+
+- Ensure you maintain the _checkpoint_ properly. Also, ensure the _translation status_ is well-displayed on the top of each translation page.
+- Utilize the diff result between the latest official repository and your own checkpoint to guide your translation.
+
+Tip: you can add the official repo as a remote to your forked repo. This way, you can still run `pnpm run docs:translation:update <lang> [<commit>]` and `npm run docs:translation:compare <lang> [<commit>]` to get the checkpoint and diff result:
+
+```bash
+# prepare the upstream remote
+git remote add upstream [email protected]:vuejs/pinia.git
+git fetch upstream v2
+
+# set the checkpoint
+pnpm run docs:translation:update <lang> upstream/v2
+
+# get the diff result
+pnpm run docs:translation:compare <lang> upstream/v2
+```
+
+<!-- TODO: add an example once we have got one -->

netlify.toml

@@ -1,4 +1,4 @@
 [build]
-command = "pnpm run docs"
+command = "pnpm run docs:build"
 ignore = "./scripts/docs-check.sh"
 publish = "packages/docs/.vitepress/dist"

package.json

@@ -9,7 +9,13 @@
     "release": "node scripts/release.mjs",
     "size": "pnpm run -r size",
     "build": "pnpm run -C packages/pinia build && pnpm run -C packages/nuxt build && pnpm run -C packages/testing build",
-    "docs": "pnpm run docs:api && pnpm run --filter ./packages/docs -r docs:build",
+    "docs": "pnpm run --filter ./packages/docs -r docs",
+    "docs:api": "pnpm run --filter ./packages/docs -r docs:api",
+    "docs:translation:compare": "pnpm run --filter ./packages/docs -r docs:translation:compare",
+    "docs:translation:update": "pnpm run --filter ./packages/docs -r docs:translation:update",
+    "docs:translation:status": "pnpm run --filter ./packages/docs -r docs:translation:status",
+    "docs:build": "pnpm run docs:api && pnpm run --filter ./packages/docs -r docs:build",
+    "docs:preview": "pnpm run --filter ./packages/docs -r docs:preview",
     "play": "pnpm run -r play",
     "build:dts": "pnpm run -r --parallel build:dts",
     "lint": "prettier -c --parser typescript \"packages/*/{src,__tests__,e2e}/**/*.[jt]s?(x)\" \"packages/docs/**/*.[jt]s\"",
@@ -18,7 +24,6 @@
     "test:vitest": "vitest --coverage",
     "test:types": "tsc --build ./tsconfig.json",
     "test:dts": "pnpm run -r test:dts",
-    "docs:api": "pnpm run --filter ./packages/docs -r docs:api",
     "postinstall": "simple-git-hooks"
   },
   "devDependencies": {

packages/docs/.vitepress/theme/index.ts

@@ -3,10 +3,16 @@ import { type Theme } from 'vitepress'
 import DefaultTheme from 'vitepress/theme'
 import AsideSponsors from './components/AsideSponsors.vue'
 // import AsideSponsors from './components/AsideSponsors.vue'
+import TranslationStatus from 'vitepress-translation-helper/ui/TranslationStatus.vue'
 import './styles/vars.css'
 import './styles/playground-links.css'
 import VueSchoolLink from './components/VueSchoolLink.vue'
 import VueMasteryLogoLink from './components/VueMasteryLogoLink.vue'
+import status from '../translation-status.json'
+
+const i18nLabels = {
+  zh: '该翻译已同步到了 ${date} 的版本，其对应的 commit hash 是 <code>${hash}</code>。',
+}
 
 const theme: Theme = {
   ...DefaultTheme,
@@ -15,6 +21,7 @@ const theme: Theme = {
       // 'home-features-after': () => h(HomeSponsors),
       'aside-ads-before': () => h(AsideSponsors),
       // 'layout-top': () => h(VueMasteryBanner),
+      'doc-before': () => h(TranslationStatus, { status, i18nLabels }),
     })
   },
 

packages/docs/.vitepress/translation-status.json

@@ -0,0 +1,6 @@
+{
+  "zh": {
+    "hash": "c67a5c9",
+    "date": "2023-12-07"
+  }
+}

packages/docs/package.json

@@ -6,12 +6,17 @@
   "scripts": {
     "docs": "vitepress dev .",
     "docs:api": "node run-typedoc.mjs",
-    "docs:build": "vitepress build ."
+    "docs:translation:compare": "v-translation compare",
+    "docs:translation:update": "v-translation update",
+    "docs:translation:status": "v-translation status",
+    "docs:build": "vitepress build .",
+    "docs:preview": "vitepress preview ."
   },
   "dependencies": {
     "@chenfengyuan/vue-countdown": "^2.1.2",
     "@vueuse/core": "^10.7.0",
     "pinia": "workspace:^2.0.18",
-    "vitepress": "1.0.0-rc.31"
+    "vitepress": "1.0.0-rc.36",
+    "vitepress-translation-helper": "^0.1.3"
   }
 }