Apply suggestions from code review

Co-authored-by: Eduardo San Martin Morote <posva@users.noreply.github.com>

.github/contributing.md

@@ -127,9 +127,9 @@ If you want to start translating the docs in a _new_ language:
 2. Modify the i18n config in `.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-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. Then after the approval and merge by the maintainers. The translation would be affected.
+5. Commit all the changes and create a pull request to our GitHub repo.
 
-To be noticed, on the top of each translation page, there would be a paragraph to indicate their translation status. So the users can know whether the translation is up-to-date or not.
+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.
 
 If you want to maintain an existing translation:
 
@@ -148,7 +148,7 @@ You can also host the translation on your own. To create one, just simply fork o
 - 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.
 
-Tips: you can add the official repo as a remote to your forked repo, and then still able to run `pnpm run docs:translation-status <lang> [<commit>]` and `npm run docs:compare-to-translate <lang> [<commit>]` to get the checkpoint and diff result:
+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

packages/docs/compare-to-translate.mjs

@@ -10,7 +10,7 @@ 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'.`
 
-const getLocaleHash = async (lang) => {
+async function getLocaleHash (lang) {
   try {
     const content = await readFile(STATUS_FILE_PATH, 'utf8')
     const data = JSON.parse(content)
@@ -21,7 +21,7 @@ const getLocaleHash = async (lang) => {
 }
 
 async function main() {
-  if (!process.argv[2] || process.argv[2] === '--help' || process.argv[2] === '-h') {
+  if (process.argv.find(arg => arg === '--help' || arg === '-h')) {
     console.log(usage)
     return
   }
@@ -31,11 +31,11 @@ async function main() {
 
   const hash = await getLocaleHash(locale)
   if (hash) {
-    console.log(`The last checkpoint of docs(${locale}) is ${hash}.\n`)
+    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 "pnpm run docs:translation-status ${locale} ${hash}" or "pnpm run docs:translation-status ${locale}${commit !== 'main' ? ' ' + commit : ''}" to update the translation status file.`)
+    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)

packages/docs/generate-translation-status.mjs

@@ -10,7 +10,7 @@ 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'.`
 
-const getCommitInfo = async (commit) => {
+async function getCommitInfo (commit) {
   try {
     const git = simpleGit()
     const log = await git.log([commit, '-n', '1'])
@@ -21,7 +21,7 @@ const getCommitInfo = async (commit) => {
   }
 }
 
-const writeLangMap = async (lang, hash, date) => {
+async function writeLangMap (lang, hash, date) {
   const data = {}
   try {
     const previousContent = await readFile(STATUS_FILE_PATH, 'utf8')
@@ -39,11 +39,7 @@ const writeLangMap = async (lang, hash, date) => {
 }
 
 async function main() {
-  if (
-    process.argv.length < 3 ||
-    process.argv[2] === '--help' ||
-    process.argv[2] === '-h'
-  ) {
+  if (process.argv.find(arg => arg === '--help' || arg === '-h')) {
     console.log(usage)
     return
   }
@@ -53,11 +49,11 @@ async function main() {
 
   const { hash, date } = await getCommitInfo(commit)
   if (!hash) {
-    console.log(`❌ No commit found for ${commit}.`)
+    console.log(`❌ No commit found for "${commit}".`)
     return
   } else {
     await writeLangMap(locale, hash, date)
-    console.log(`✅ Updated ${locale} to ${hash} (${date})`)
+    console.log(`✅ Updated ${locale} to "${hash}" (${date})`)
   }
 }