README.md

VitePress Translation Helper

A translation toolkit for VitePress, made by vuejs-translations.

Usage

1. CLI commands

Usage:
  v-translation status [<locale>] [--status-file=<file-path>]
  v-translation compare <locale> [<commit>] [--status-file=<file-path>] [--path=<diff-path>]
  v-translation update <locale> [<commit>] [--status-file=<file-path>]
  v-translation --help
  v-translation --version

Arguments:
  locale: The target locale to check/compare/update.
  commit: The target commit to compare/update. It could be a branch, a tag, or a hash. Default to 'main'.

Options:
  -s, 
  --status-file:
    The path to the translation status file. Default to './.vitepress/translation-status.json'.
  -p,
  --path:
    The target files/directories to compare. You can set multiple paths if you like. Default to the whole repository.
  -h,
  --help:
    Print this help message.
  -v,
  --version:
    Print the version number.

Examples:
  v-translation status
  v-translation status zh
  v-translation compare zh
  v-translation compare zh main
  v-translation compare zh 1cf14f8
  v-translation compare zh --path=docs
  v-translation compare zh main --path=docs/guide --path=docs/api
  v-translation update zh
  v-translation update zh main
  v-translation update zh 1cf14f8

2. Translation Status UI

Put the translation status UI component into your VitePress theme.

import { h } from 'vue'
import { Theme, useData } from 'vitepress'
import DefaultTheme from 'vitepress/theme'

// Import the Translation Status UI component.
import TranslationStatus from 'vitepress-translation-helper/ui/TranslationStatus.vue'
// This is the translation status file generated by `v-translation update`.
import status from '../translation-status.json'

// Optional: custom i18n labels for your locales
const i18nLabels = {
  localeA: 'xxx ${date} xxx ${hash} xxx',
  localeB: 'xxx ${date} xxx ${hash} xxx',
  // ...
}

const theme: Theme = {
  ...DefaultTheme,
  Layout() {
    return h(DefaultTheme.Layout, null, {
      // Put the Translation Status UI component into the layout.
      'doc-before': () => h(TranslationStatus, { status, i18nLabels }),
    })
  },
}

export default theme

The default i18n label is:

'The translation is synced to the docs on ${date} of which the commit hash is <code>${hash}</code>.'