docs: non-checkpoint-branch workflow (#1855)

* add translation status on page top

* refactor: use mjs and promises

* chore: format contribution guidelines

* chore: update translation workflow to remove checkpoint branches

* fix: wrong git diff arg in compare-to-translate

* chore: make the translation status generator compatible with legacy log format

* chore: update translation workflow guide and ignore translation-status.json

* chore: add docs:preview command

* chore: improve translation workflow in docs

* chore: update contributing docs

* chore: update contributing docs

* Apply suggestions from code review

Co-authored-by: Eduardo San Martin Morote <[email protected]>

* Update contributing.md

---------

Co-authored-by: Eduardo San Martin Morote <[email protected]>
Co-authored-by: Eduardo San Martin Morote <[email protected]>

Author: Jinjiang

.github/contributing.md

@@ -117,40 +117,51 @@ Currently, all the docs can be found in `packages/docs`. It contains the English
 
 Besides that, the `.vitepress` sub-folder is used to put the config and theme, including the i18n information.
 
-Consider the following two options in order to contribute to the translations:
+Contributing to the English docs is the same as contributing to the source code. You can simply create a pull request to our GitHub repo. However, if you would like to contribute to the translations, there are 2 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:
+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 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.
+4. Create a checkpoint for your language by running `pnpm run docs:translation-status <lang> [<commit>]`. A checkpoint is the hash and date of the latest commit when you do the translation. The checkpoint information would be stored in the status file `packages/docs/.vitepress/translation-status.json`. _It's important for the long-term maintenance since all the further translation sync-ups would be based on their previous checkpoints._ Usually you can skip the commit argument because the default value is `main`.
+5. Commit all the changes and create a pull request to our GitHub repo.
 
-If you want to maintain a existing translation:
+We will have a paragraph right at the top of each translation page that shows the status of the translation. That way, users can easily figure out if the translation is up-to-date or lags behind the English version.
 
-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`.
+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:
 
-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).
+1. See what translation you need to sync up with the original docs. There are 2 popular ways:
+    1. Via the [GitHub Compare](https://github.com/vuejs/router/compare/) page: only see the changes in `packages/docs/*` from the checkpoint hash to `main` branch. You can find the checkpoint hash for your language via the translation status file `packages/docs/.vitepress/translation-status.json`. And the compare page can be directly opened with the hash as part of the URL e.g. https://github.com/vuejs/router/compare/e008551...main
+    2. Via a local command: `pnpm run docs:compare-to-translate <lang> [<commit>]`.
+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-status <lang> [<commit>]`.
+4. Commit all the changes and create a pull request to our GitHub repo.
+
+<!-- TODO: add an example once we have got one -->
 
 ### Self-host the translation
 
 You can also host the translation on your own. To create one, just simply 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:
 
-1. Ensure you create a _checkpoint branch_ (for example, a branch named sync). This branch should always align with the commit of the original documentation that corresponds to your most recent translation.
-2. Utilize the diff result between the latest official repository and your own by using the git diff command or the GitHub Compare page to guide your translation.
-3. Complete the translation process.
-4. Update the _checkpoint branch_ accordingly.
+- Ensure you maintain the _checkpoint_ properly. And 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-status <lang> [<commit>]` and `npm run docs:compare-to-translate <lang> [<commit>]` to get the checkpoint and diff result:
+
+```bash
+# prepare the upstream remote
+git remote add upstream [email protected]:vuejs/router.git
+git fetch upstream main
+
+# set the checkpoint
+pnpm run docs:translation-status <lang> upstream/main
+
+# get the diff result
+pnpm run docs:compare-to-translate <lang> upstream/main
+```
 
 <!-- TODO: add an example once we have got one -->
 

package.json

@@ -13,8 +13,12 @@
     "size": "node scripts/check-size.mjs",
     "build": "pnpm run -r build",
     "build:dts": "pnpm run -r build:dts",
+    "docs": "pnpm run --filter ./packages/docs -r docs",
     "docs:api": "pnpm run --filter ./packages/docs -r docs:api",
+    "docs:compare-to-translate": "pnpm run --filter ./packages/docs -r docs:compare-to-translate",
+    "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:size": "pnpm run -r build:size",
     "lint": "pnpm run lint:script && pnpm run lint:html",

packages/docs/.vitepress/theme/components/TranslationStatus.vue

@@ -0,0 +1,40 @@
+<script lang="ts">
+const originalLang = 'root'
+const i18nLabels: {
+  [lang: string]: string
+} = {
+  en: 'The translation is synced to the docs on ${date} of which the commit hash is <code>${hash}</code>.',
+  zh: '该翻译已同步到了 ${date} 的版本，其对应的 commit hash 是 <code>${hash}</code>。',
+}
+</script>
+
+<script setup lang="ts">
+import { computed } from 'vue'
+import { useData } from 'vitepress'
+import status from '../../translation-status.json'
+
+const { site } = useData()
+const label = computed<string>(() => {
+  const localeIndex = site.value.localeIndex
+  if (!localeIndex || localeIndex === originalLang || !status[localeIndex]) {
+    return ''
+  }
+  const { date, hash } = status[localeIndex]
+  return (i18nLabels[localeIndex] || i18nLabels.en)
+    .replace('${date}', `<time>${date}</time>`)
+    .replace('${hash}', `<code>${hash.substring(0, 7)}</code>`)
+})
+</script>
+
+<template>
+  <div v-if="label" class="text-status" v-html="label"></div>
+</template>
+
+<style scoped>
+.text-status {
+  padding: 1em 1.25em;
+  font-size: small;
+  text-align: right;
+  color: var(--vp-c-text-2);
+}
+</style>

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

@@ -3,6 +3,7 @@ import { Theme, useData } from 'vitepress'
 import DefaultTheme from 'vitepress/theme'
 import AsideSponsors from './components/AsideSponsors.vue'
 // import HomeSponsors from './components/HomeSponsors.vue'
+import TranslationStatus from './components/TranslationStatus.vue'
 import './styles/vars.css'
 import './styles/sponsors.css'
 import VueSchoolLink from './components/VueSchoolLink.vue'
@@ -14,6 +15,7 @@ const theme: Theme = {
     return h(DefaultTheme.Layout, null, {
       // 'home-features-after': () => h(HomeSponsors),
       'aside-ads-before': () => h(AsideSponsors),
+      'doc-before': () => h(TranslationStatus),
     })
   },
 

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

@@ -0,0 +1,6 @@
+{
+  "zh": {
+    "hash": "1a3a28f",
+    "date": "2023-04-08"
+  }
+}

packages/docs/compare-to-translate.mjs

@@ -0,0 +1,45 @@
+// @ts-check
+import { readFile } from 'fs/promises'
+import simpleGit from 'simple-git'
+
+// The path to the translation status file.
+const STATUS_FILE_PATH = './.vitepress/translation-status.json'
+
+const usage = `
+Usage: pnpm run docs:compare-to-translate <locale> [<commit>]
+  locale: The target locale to compare.
+  commit: The target commit to compare. It could be a branch, a tag, or a hash. Default to 'main'.`
+
+async function getLocaleHash (lang) {
+  try {
+    const content = await readFile(STATUS_FILE_PATH, 'utf8')
+    const data = JSON.parse(content)
+    return data[lang]?.hash
+  } catch (err) {
+    console.log('No previous status file. Will create a new one.')
+  }
+}
+
+async function main() {
+  if (process.argv.find(arg => arg === '--help' || arg === '-h')) {
+    console.log(usage)
+    return
+  }
+
+  const locale = process.argv[2]
+  const commit = process.argv[3] || 'main'
+
+  const hash = await getLocaleHash(locale)
+  if (hash) {
+    console.log(`The last checkpoint of docs(${locale}) is "${hash}".\n`)
+    const git = simpleGit()
+    const result = await git.diff([`${hash}..${commit}`, '.'])
+    console.log(result)
+    console.log(`\nAfter finishing the translation, you can run\n"pnpm run docs:translation-status ${locale} ${hash}"\nor\n"pnpm run docs:translation-status ${locale}${commit !== 'main' ? ' ' + commit : ''}"\nto update the translation status file.`)
+  } else {
+    console.log(`No docs(${locale}) checkpoint found.\n`)
+    console.log(usage)
+  }
+}
+
+main()

packages/docs/generate-translation-status.mjs

@@ -0,0 +1,60 @@
+// @ts-check
+import { writeFile, readFile } from 'fs/promises'
+import simpleGit from 'simple-git'
+
+// The path to the translation status file.
+const STATUS_FILE_PATH = './.vitepress/translation-status.json'
+
+const usage = `
+Usage: pnpm run docs:translation-status <locale> [<commit>]
+  locale: The target locale to update.
+  commit: The target commit to update. It could be a branch, a tag, or a hash. Default to 'main'.`
+
+async function getCommitInfo (commit) {
+  try {
+    const git = simpleGit()
+    const log = await git.log([commit, '-n', '1'])
+    const { hash, date } = log.latest
+    return { hash, date: new Date(date).toISOString().substring(0, 10) }
+  } catch (err) {
+    return { hash: '', date: '' }
+  }
+}
+
+async function writeLangMap (lang, hash, date) {
+  const data = {}
+  try {
+    const previousContent = await readFile(STATUS_FILE_PATH, 'utf8')
+    const previousJson = JSON.parse(previousContent)
+    Object.assign(data, previousJson)
+  }
+  catch (err) {
+    console.log('No previous status file. Will create a new one.')
+  }
+  data[lang] = {
+    hash,
+    date,
+  }
+  await writeFile(STATUS_FILE_PATH, JSON.stringify(data, null, 2))
+}
+
+async function main() {
+  if (process.argv.find(arg => arg === '--help' || arg === '-h')) {
+    console.log(usage)
+    return
+  }
+
+  const locale = process.argv[2]
+  const commit = process.argv[3] || 'main'
+
+  const { hash, date } = await getCommitInfo(commit)
+  if (!hash) {
+    console.log(`❌ No commit found for "${commit}".`)
+    return
+  } else {
+    await writeLangMap(locale, hash, date)
+    console.log(`✅ Updated ${locale} to "${hash}" (${date})`)
+  }
+}
+
+main()

packages/docs/package.json

@@ -6,9 +6,13 @@
   "scripts": {
     "docs": "vitepress dev .",
     "docs:api": "node run-typedoc.mjs",
-    "docs:build": "vitepress build ."
+    "docs:compare-to-translate": "node compare-to-translate.mjs",
+    "docs:translation-status": "node generate-translation-status.mjs",
+    "docs:build": "vitepress build .",
+    "docs:preview": "vitepress preview ."
   },
   "dependencies": {
+    "simple-git": "^3.18.0",
     "vitepress": "1.0.0-rc.31",
     "vue-router": "workspace:*"
   }