refactor(core): reorganize functions (#7037)

packages/docusaurus-utils/src/__tests__/i18nUtils.test.ts

@@ -5,10 +5,12 @@
  * LICENSE file in the root directory of this source tree.
  */
 
+import path from 'path';
 import {
   mergeTranslations,
   updateTranslationFileMessages,
   getPluginI18nPath,
+  localizePath,
 } from '../i18nUtils';
 
 describe('mergeTranslations', () => {
@@ -93,3 +95,85 @@ describe('getPluginI18nPath', () => {
     ).toMatchInlineSnapshot(`"/i18n/zh-Hans/plugin-content-docs"`);
   });
 });
+
+describe('localizePath', () => {
+  it('localizes url path with current locale', () => {
+    expect(
+      localizePath({
+        pathType: 'url',
+        path: '/baseUrl',
+        i18n: {
+          defaultLocale: 'en',
+          locales: ['en', 'fr'],
+          currentLocale: 'fr',
+          localeConfigs: {},
+        },
+        options: {localizePath: true},
+      }),
+    ).toBe('/baseUrl/fr/');
+  });
+
+  it('localizes fs path with current locale', () => {
+    expect(
+      localizePath({
+        pathType: 'fs',
+        path: '/baseFsPath',
+        i18n: {
+          defaultLocale: 'en',
+          locales: ['en', 'fr'],
+          currentLocale: 'fr',
+          localeConfigs: {},
+        },
+        options: {localizePath: true},
+      }),
+    ).toBe(`${path.sep}baseFsPath${path.sep}fr`);
+  });
+
+  it('localizes path for default locale, if requested', () => {
+    expect(
+      localizePath({
+        pathType: 'url',
+        path: '/baseUrl/',
+        i18n: {
+          defaultLocale: 'en',
+          locales: ['en', 'fr'],
+          currentLocale: 'en',
+          localeConfigs: {},
+        },
+        options: {localizePath: true},
+      }),
+    ).toBe('/baseUrl/en/');
+  });
+
+  it('does not localize path for default locale by default', () => {
+    expect(
+      localizePath({
+        pathType: 'url',
+        path: '/baseUrl/',
+        i18n: {
+          defaultLocale: 'en',
+          locales: ['en', 'fr'],
+          currentLocale: 'en',
+          localeConfigs: {},
+        },
+        // options: {localizePath: true},
+      }),
+    ).toBe('/baseUrl/');
+  });
+
+  it('localizes path for non-default locale by default', () => {
+    expect(
+      localizePath({
+        pathType: 'url',
+        path: '/baseUrl/',
+        i18n: {
+          defaultLocale: 'en',
+          locales: ['en', 'fr'],
+          currentLocale: 'en',
+          localeConfigs: {},
+        },
+        // options: {localizePath: true},
+      }),
+    ).toBe('/baseUrl/');
+  });
+});

packages/docusaurus-utils/src/i18nUtils.ts

@@ -7,8 +7,13 @@
 
 import path from 'path';
 import _ from 'lodash';
-import type {TranslationFileContent, TranslationFile} from '@docusaurus/types';
+import type {
+  TranslationFileContent,
+  TranslationFile,
+  I18n,
+} from '@docusaurus/types';
 import {DEFAULT_PLUGIN_ID, I18N_DIR_NAME} from './constants';
+import {normalizeUrl} from './urlUtils';
 
 /**
  * Takes a list of translation file contents, and shallow-merges them into one.
@@ -65,3 +70,46 @@ export function getPluginI18nPath({
     ...subPaths,
   );
 }
+
+/**
+ * Takes a path and returns a localized a version (which is basically `path +
+ * i18n.currentLocale`).
+ */
+export function localizePath({
+  pathType,
+  path: originalPath,
+  i18n,
+  options = {},
+}: {
+  /**
+   * FS paths will treat Windows specially; URL paths will always have a
+   * trailing slash to make it a valid base URL.
+   */
+  pathType: 'fs' | 'url';
+  /** The path, URL or file path, to be localized. */
+  path: string;
+  /** The current i18n context. */
+  i18n: I18n;
+  options?: {
+    /**
+     * By default, we don't localize the path of defaultLocale. This option
+     * would override that behavior. Setting `false` is useful for `yarn build
+     * -l zh-Hans` to always emit into the root build directory.
+     */
+    localizePath?: boolean;
+  };
+}): string {
+  const shouldLocalizePath: boolean =
+    //
+    options.localizePath ?? i18n.currentLocale !== i18n.defaultLocale;
+
+  if (!shouldLocalizePath) {
+    return originalPath;
+  }
+  // FS paths need special care, for Windows support
+  if (pathType === 'fs') {
+    return path.join(originalPath, i18n.currentLocale);
+  }
+  // Url paths; add a trailing slash so it's a valid base URL
+  return normalizeUrl([originalPath, i18n.currentLocale, '/']);
+}

packages/docusaurus-utils/src/index.ts

@@ -32,6 +32,7 @@ export {
   mergeTranslations,
   updateTranslationFileMessages,
   getPluginI18nPath,
+  localizePath,
 } from './i18nUtils';
 export {
   removeSuffix,