Skip to content

DreamOfIce/vuepress-plugin-i18n

Folders and files

NameName
Last commit message
Last commit date

Latest commit

85be223 · Sep 26, 2023
May 18, 2023
May 6, 2023
Sep 26, 2023
Mar 30, 2023
Apr 28, 2023
Mar 15, 2023
May 6, 2023
Apr 28, 2023
Apr 6, 2023
Jul 9, 2023
Sep 26, 2023
Mar 15, 2023
Sep 26, 2023
Sep 26, 2023
Sep 26, 2023
Sep 26, 2023
Sep 26, 2023
Jul 9, 2023

Repository files navigation

vuepress-plugin-i18n

I18n plugin for VuePress v2

中文版本

Features

  • Fill non-existent pages in translation directories
  • Translation outdated alert (based on git or file info)
  • HMR support
  • Development guide

Usage

Install

npm install -D vuepress-plugin-i18n

Or using pnpm:

pnpm add -D vuepress-plugin-i18n

Enable plugin

import { defineUserConfig } from "vuepress";
import i18nPlugin from "vuepress-plugin-i18n";

export default defineUserConfig({
  // ...
  plugins: [
    i18nPlugin({
      // plugin options
    }),
  ],
});

Options

Plugin options

interface I18nPluginOptions {
  /**
   * Path prefix for source language version
   * @default "/"
   */
  baseLocalePath?: string;
  /**
   * Page filter
   * @param page VuePress page object
   * @returns Whether the page should be included
   */
  filter?: (page: Page) => boolean;
  /**
   * Custom locales for i18n plugin
   */
  locales?: Record<string, Partial<I18nPluginLocaleData>>;
  /**
   * Add tag `untranslated` or `outdated` to page
   * need to load before [vuepress-plugin-blog2]{@link https://www.npmjs.com/package/vuepress-plugin-blog2}
   * @default false
   */
  tag?: boolean;
  /**
   * Tip container options
   * @see I18nPluginTipOptions
   * @default true
   */
  tip?: I18nPluginTipOptions | boolean;
  /**
   * Link to translation guide(in default locale)
   */
  translationGuide?: string;
  /**
   * Calculate updatedTime when not exist
   * - `git`: read updated time from git
   * - `file`: read updated time from file info
   * - a function:
   *   @param page VuePress page object
   *   @param app VuePress app
   *   @returns a mode name or a timestamp
   * @note git mode may significantly slow down dev server startup
   * @default (_page, app) => app.env.isBuild || app.env.isDebug ? "git" : undefined
   */
  updatedTime?:
    | "git"
    | "file"
    | ((page: Page, app: App) => number | undefined | "git" | "file");
}

interface I18nPluginTipOptions {
  /**
   * Enable tip containers
   * @default true
   */
  enable?: boolean;
  /**
   * Classes of the container div (type of container will always be add)
   * @default ["custom-container", "hint-container"]
   */
  containerClass?: string[];
  /**
   * Classes of the container title
   * @default ["custom-container-title", "hint-container-title"]
   */
  titleClass?: string[];
  /**
   * Name for tip component, which will be inserted at the top of the page
   * NOTE: You need to import your custom component globally by yourself
   * @default "I18nTip"
   */
  tipComponent: string;
}

Localization options

interface I18nPluginLocaleData {
  /**
   * @description RFC5646 Language code
   * @example "en-US", "zh-CN"
   */
  lang: string;
  untranslated: {
    /**
     * @description Title of untranslated page tip
     */
    title: string;
    /**
     * Content of the container
     * @param linkRenderer link rendering helper
     * @param translationGuide links to translation guides (ignore the relevant section when empty)
     * @returns localised text
     */
    content: (linkRenderer: LinkRenderer, translationGuide?: string) => string;
  };
  outdated: {
    /**
     * @description Title of obsolete page tip
     */
    title: string;
    /**
     * Content of the container
     * @param linkRenderer link rendering helper
     * @param sourceUpdateTime unix timestamp for source page
     * @param translationUpdateTime unix timestamp for translation page
     * @param sourceLink url of the source page
     * @returns localised text
     */
    content: (
      linkRenderer: LinkRenderer,
      sourceUpdateTime: number,
      translationUpdateTime: number,
      sourceLink: string,
    ) => string;
  };
}

/**
 * Link rendering helper
 * @param text link text
 * @param href target URL
 * @returns html string
 */
type LinkRenderer = (text: string, href: string) => string;

Advanced

Client helper

You can use the useI18nData function to import the i18n information for the current page:

import { useI18nData } from "vuepress-plugin-i18n";

const i18nData = useI18nData(); // will return a computed ref of I18nData
console.log(i18nData.value);

Type definition of computed property returned:

interface I18nData {
  isOutdated: boolean;
  isUntranslated: boolean;
  locale: I18nPluginLocaleData;
  options: {
    baseLocalePath: string;
    containerClass: string[];
    titleClass: string[];
  };
  pathLocale: string;
  sourceLink: string | undefined;
  sourceUpdatedTime: number | undefined;
  translationGuide: string | undefined;
  updatedTime: number | undefined;
}

A common use of this function is to write custom tip component, For an example, please refer to the source code of default component

License

MIT