refactor(git-changelog): migrate i18n to ui config (#213)

* refactor(git-changelog): migrate i18n to ui config 1. The `locales` in the original Vite plugin `GitChangelogMarkdownSection` no longer need to be configured and have been migrated to the UI configuration under `locales`: 1. `changelog.title` 2. `contributors.title`; 2. In order to better structure the organization of the i18n fields, the original 1. `noLogs` i18n configuration changed to `changelog.noData`; 2. `noContributors` i18n configuration was changed to `contributors.noData`. 3. `lastEdited` i18n Configuration changed to `lastEdited`. 4. `lastEditedDateFnsLocaleName` configuration changed to `changelog.lastEditedDateFnsLocaleName` 5. `viewFullHistory` i18n Configuration changed to `changelog.viewFullHistory` 6. `committedOn` i18n configuration changed to `changelog.committedOn` * fix: migrate vite.config.ts * docs: update docs/pages/en/releases/migrations/v1-to-v2.md * docs: update docs/pages/zh-CN/releases/migrations/v1-to-v2.md --------- Signed-off-by: Neko Ayaka <neko@ayaka.moe> Co-authored-by: BeiyanYunyi <14120445+BeiyanYunyi@users.noreply.github.com> Co-authored-by: Northword <44738481+northword@users.noreply.github.com>
nolebase · May 15, 2024 · 04fb100 · 04fb100
1 parent d557690
commit 04fb100
Show file tree

Hide file tree

Showing 21 changed files with 371 additions and 696 deletions.
diff --git a/cspell.config.yaml b/cspell.config.yaml
@@ -55,6 +55,7 @@ words:
   - uncrypto
   - unlazy
   - unocss
+  - Vite
   - vitepress
   - vueuse
 ignoreWords: []

diff --git a/docs/pages/en/integrations/vitepress-plugin-git-changelog/configure-ui.md b/docs/pages/en/integrations/vitepress-plugin-git-changelog/configure-ui.md
@@ -122,6 +122,12 @@ export const Theme: ThemeConfig = {
 
 ## Options inside
 
+::: warning Deprecating warning
+
+We have changed the structure of locales config since `2.0.0-rc14`, and the old structure will be deprecated in the next major version. Please update your configuration according to the new structure. For migration guides, see [Migrate from v1 to v2](/pages/en/releases/migrations/v1-to-v2).
+
+:::
+
 ::: details Complete configurable options
 
 ```typescript twoslash
@@ -133,29 +139,47 @@ interface SocialEntry {
 
 interface Locale extends Record<string, any> {
   /**
-   * What to display when there are no logs
-   */
-  noLogs?: string
-  /**
-   * What to display when there are no contributors
-   */
-  noContributors?: string
-  /**
-   * What to display when the page was last edited
+   * The changelog section configuration
    */
-  lastEdited?: string
-  /**
-   * The name of the locale to use for date-fns
-   */
-  lastEditedDateFnsLocaleName?: string
-  /**
-   * What to display when the user wants to view the full history
-   */
-  viewFullHistory?: string
+  changelog?: {
+    /**
+     * The title of the changelog section
+     */
+    title?: string
+    /**
+     * What to display when there are no logs
+     */
+    noData?: string
+    /**
+     * What to display when the page was last edited
+     */
+    lastEdited?: string
+    /**
+     * The name of the locale to use for date-fns
+     */
+    lastEditedDateFnsLocaleName?: string
+    /**
+     * What to display when the user wants to view the full history
+     */
+    viewFullHistory?: string
+    /**
+     * What to display when the commit was committed
+     */
+    committedOn?: string
+  }
   /**
-   * What to display when the commit was committed
+   * The contributors section configuration
    */
-  committedOn?: string
+  contributors?: {
+    /**
+     * The title of the contributors section
+     */
+    title?: string
+    /**
+     * What to display when there are no contributors
+     */
+    noData?: string
+  }
 }
 // ---cut---
 /**
@@ -176,18 +200,24 @@ export interface Options {
    * {
    *  locales: {
    *    'en': {
-   *      noLogs: 'No recent changes',
-   *      lastEdited: 'This page was last edited {{daysAgo}}',
-   *      lastEditedDateFnsLocaleName: 'enUS',
-   *      viewFullHistory: 'View full history',
-   *      committedOn: ' on {{date}}',
+   *      changelog: {
+   *        title: 'Changelog',
+   *        noData: 'No recent changes',
+   *        lastEdited: 'This page was last edited {{daysAgo}}',
+   *        lastEditedDateFnsLocaleName: 'enUS',
+   *        viewFullHistory: 'View full history',
+   *        committedOn: ' on {{date}}',
+   *      }
    *    },
    *    'zh-CN': {
-   *      noLogs: '暂无最近变更历史',
-   *      lastEdited: '本页面最后编辑于 {{daysAgo}}',
-   *      lastEditedDateFnsLocaleName: 'zhCN',
-   *      viewFullHistory: '查看完整历史',
-   *      committedOn: '于 {{date}} 提交',
+   *       changelog: {
+   *         title: '页面历史'
+   *         noData: '暂无最近变更历史',
+   *         lastEdited: '本页面最后编辑于 {{daysAgo}}',
+   *         lastEditedDateFnsLocaleName: 'zhCN',
+   *         viewFullHistory: '查看完整历史',
+   *         committedOn: '于 {{date}} 提交',
+   *       }
    *     },
    *   }
    * }
@@ -287,6 +317,12 @@ export const Theme: ThemeConfig = {
 
 ### Locales options
 
+::: warning Deprecating warning
+
+We have changed the structure of locales config since `2.0.0-rc14`, and the old structure will be deprecated in the next major version. Please update your configuration according to the new structure. For migration guides, see [Migrate from v1 to v2](/pages/en/releases/migrations/v1-to-v2).
+
+:::
+
 ::: details Complete internationalization field options
 
 ```typescript twoslash
@@ -295,29 +331,47 @@ export const Theme: ThemeConfig = {
  */
 interface Locale {
   /**
-   * What to display when there are no logs
-   */
-  noLogs?: string
-  /**
-   * What to display when there are no contributors
-   */
-  noContributors?: string
-  /**
-   * What to display when the page was last edited
+   * The changelog section configuration
    */
-  lastEdited?: string
-  /**
-   * The name of the locale to use for date-fns
-   */
-  lastEditedDateFnsLocaleName?: string
-  /**
-   * What to display when the user wants to view the full history
-   */
-  viewFullHistory?: string
+  changelog?: {
+    /**
+     * The title of the changelog section
+     */
+    title?: string
+    /**
+     * What to display when there are no logs
+     */
+    noData?: string
+    /**
+     * What to display when the page was last edited
+     */
+    lastEdited?: string
+    /**
+     * The name of the locale to use for date-fns
+     */
+    lastEditedDateFnsLocaleName?: string
+    /**
+     * What to display when the user wants to view the full history
+     */
+    viewFullHistory?: string
+    /**
+     * What to display when the commit was committed
+     */
+    committedOn?: string
+  }
   /**
-   * What to display when the commit was committed
+   * The contributors section configuration
    */
-  committedOn?: string
+  contributors?: {
+    /**
+     * The title of the contributors section
+     */
+    title?: string
+    /**
+     * What to display when there are no contributors
+     */
+    noData?: string
+  }
 }
 ```
 

diff --git a/.../pages/en/integrations/vitepress-plugin-git-changelog/configure-vite-plugins.md b/.../pages/en/integrations/vitepress-plugin-git-changelog/configure-vite-plugins.md
@@ -1,5 +1,13 @@
 # Configure Vite plugins
 
+::: danger Deprecating the `locales` field of `GitChangelogMarkdownSection` plugin options
+
+We migrated the `locales` configurations to [UI config](/pages/en/integrations/vitepress-plugin-git-changelog/configure-ui#locales-options). You no longer need to set `locales` for `GitChangelogMarkdownSection` plugin.
+
+For information, please refer to [Migrate from v1 to v2](/pages/en/releases/migrations/v1-to-v2).
+
+:::
+
 Besides the UI widget components, Git-based page histories offer another two Vite plugins for data fetching and rendering. These plugins are `GitChangelog` and `GitChangelogMarkdownSection`.
 
 ### Configure Vite plugins
@@ -161,33 +169,9 @@ It does have more options to configure.
 ::: details Full list of options
 
 ```typescript twoslash
-import type { Context, Locale } from '@nolebase/vitepress-plugin-git-changelog/vite'
+import type { Context } from '@nolebase/vitepress-plugin-git-changelog/vite'
 // ---cut---
 interface GitChangelogMarkdownSectionOptions {
-  /**
-   * The locales options
-   */
-  locales?: Record<string, Locale>
-  /**
-   * The getter function to get the title of the changelog section
-   *
-   * @param code - raw markdown code (comes from vite when transform hook is called)
-   * @param id - the current transforming module ID (comes from vite when transform hook is called)
-   * @param context - the context object, contains several helper functions
-   * @returns string
-   * @default () => 'Changelog'
-   */
-  getChangelogTitle?: (code: string, id: string, context: Context) => string
-  /**
-   * The getter function to get the title of the contributors section
-   *
-   * @param code - raw markdown code (comes from vite when transform hook is called)
-   * @param id - the current transforming module ID (comes from vite when transform hook is called)
-   * @param context - the context object, contains several helper functions
-   * @returns string
-   * @default () => 'Contributors'
-   */
-  getContributorsTitle?: (code: string, id: string, context: Context) => string
   /**
    * The list of file names to exclude from the transformation
    *
@@ -221,85 +205,6 @@ interface GitChangelogMarkdownSectionOptions {
 
 :::
 
-#### Internationalization
-
-The `GitChangelogMarkdownSection` plugin supports internationalization. You can configure the `locales` option to provide the translations for the section titles.
-
-::: tip Why internationalization again, in Vite plugin, seriously?
-
-VitePress has a function called [outline](https://vitepress.dev/reference/default-theme-config#outline), where it read all the heading titles in one page and generate the sidebar navigation based on these data.
-
-So in order to make the changelog (page history) and contributors section titles to be included into outline, we have to inject them into the Markdown before it got rendered into HTML, then pass them to VitePress to render the pages into HTML.
-
-And transforming and manipulating `markdown-it` AST tree is a tough work to do by comparing to directly manipulate them in Vite plugins, or through Remark API, but this would be another story for another time.
-
-In conclusion, we have to inject the sections into the Markdown before it got rendered into HTML, as well as the internationalization support.
-
-:::
-
-```typescript twoslash
-import { defineConfig } from 'vite'
-import { // [!code focus]
-  GitChangelogMarkdownSection, // [!code focus]
-} from '@nolebase/vitepress-plugin-git-changelog/vite' // [!code focus]
-
-export default defineConfig({
-  plugins: [
-    GitChangelogMarkdownSection({ // [!code focus]
-      locales: { // [!code focus]
-        'zh-CN': { // [!code focus]
-          gitChangelogMarkdownSectionTitles: { // [!code focus]
-            changelog: '文件历史', // [!code focus]
-            contributors: '贡献者', // [!code focus]
-          }, // [!code focus]
-        }, // [!code focus]
-        'en': { // [!code focus]
-          gitChangelogMarkdownSectionTitles: { // [!code focus]
-            changelog: 'File History', // [!code focus]
-            contributors: 'Contributors', // [!code focus]
-          }, // [!code focus]
-        }, // [!code focus]
-      }, // [!code focus]
-    }), // [!code focus]
-  ],
-  // other vite configurations...
-})
-```
-
-or if you would like to dynamically generate the translations:
-
-```typescript twoslash
-import { join } from 'node:path'
-import { defineConfig } from 'vite'
-import { // [!code focus]
-  GitChangelogMarkdownSection, // [!code focus]
-} from '@nolebase/vitepress-plugin-git-changelog/vite' // [!code focus]
-
-export default defineConfig({
-  plugins: [
-    GitChangelogMarkdownSection({ // [!code focus]
-      getChangelogTitle: (_, __, { helpers }): string => {
-        if (helpers.idStartsWith(join('pages', 'en')))
-          return 'File History'
-        if (helpers.idStartsWith(join('pages', 'zh-CN')))
-          return '文件历史'
-
-        return 'File History'
-      },
-      getContributorsTitle: (_, __, { helpers }): string => {
-        if (helpers.idStartsWith(join('pages', 'en')))
-          return 'Contributors'
-        if (helpers.idStartsWith(join('pages', 'zh-CN')))
-          return '贡献者'
-
-        return 'Contributors'
-      },
-    }), // [!code focus]
-  ],
-  // other vite configurations...
-})
-```
-
 #### Excluding a page from the transformation of `GitChangelogMarkdownSection`
 
 You can exclude a page from the transformation of `GitChangelogMarkdownSection` by adding the `nolebase.gitChangelog` or `gitChangelog` frontmatter to the page:

diff --git a/docs/pages/en/releases/migrations/v1-to-v2.md b/docs/pages/en/releases/migrations/v1-to-v2.md
@@ -210,13 +210,24 @@ import '@nolebase/vitepress-plugin-highlight-targeted-heading/client/style.css'
 2. `nameAliases` now deprecated, please use `mapByNameAliases` instead, which is more clear and consistent with other plugins.
 3. `emailAliases` now deprecated, please use `mapByEmailAliases` instead, which is more clear and consistent with other plugins.
 4. Added new `username` field, which is the username of the author on GitHub used to fetch the avatar.
+5. The `locales` in the original Vite plugin `GitChangelogMarkdownSection` no longer need to be configured and have been migrated to the UI configuration under `locales`:
+	1. `changelog.title`
+	2. `contributors.title`;
+6. In order to better structure the organization of the i18n fields, the original
+	1. `noLogs` i18n configuration changed to `changelog.noData`; 
+	2. `noContributors` i18n configuration was changed to `contributors.noData`.
+	3. `lastEdited` i18n Configuration changed to `lastEdited`.
+	4. `lastEditedDateFnsLocaleName` configuration changed to `changelog.lastEditedDateFnsLocaleName`
+	5. `viewFullHistory` i18n Configuration changed to `changelog.viewFullHistory`
+	6. `committedOn` i18n configuration changed to `changelog.committedOn`
 
 ### `Vite` config
 
-1. `includeDirs` and `includeExtensions` have been deprecated and merged into `include`, which is a list of glob modes with `!` negation.
-2. If a renderable page file located outside of the VitePress root (where `.vitepress` lives), please configure the `cwd` (current working directory) to the parent directory of the page files. (For example, in a Monorepo, if the source file that rendered a page s located outside of `docs/`, you need to set `cwd` to the root directory of the Monorepo instead of the root of VitePress.)
-3. No longer needed to configure `rewritePaths`, therefor `rewritePaths` is now deprecated, can be safely removed.
-4. `rewritePaths` pattern should be configured in the against to filesystem paths, not the URL route paths.
+1. There is no longer a need to configure the `locales` field for `GitChangelogMarkdownSection`, and all of the internationalized i18n configuration has been migrated to the UI configuration.
+2. `includeDirs` and `includeExtensions` have been deprecated and merged into `include`, which is a list of glob modes with `!` negation.
+3. If a renderable page file located outside of the VitePress root (where `.vitepress` lives), please configure the `cwd` (current working directory) to the parent directory of the page files. (For example, in a Monorepo, if the source file that rendered a page s located outside of `docs/`, you need to set `cwd` to the root directory of the Monorepo instead of the root of VitePress.)
+4. No longer needed to configure `rewritePaths`, therefor `rewritePaths` is now deprecated, can be safely removed.
+5. `rewritePathsBy` pattern should be configured in the against to filesystem paths, not the URL route paths.
 
 ## Previewing image (social media card) generation