extract code to docusaurus utils

packages/docusaurus-plugin-content-pages/src/index.ts

@@ -21,7 +21,8 @@ import {
   parseMarkdownFile,
   isUnlisted,
   isDraft,
-  findAsyncSequential,
+  getLocalizedSourcePath,
+  filterFilesWithLocaleExtension,
 } from '@docusaurus/utils';
 import {validatePageFrontMatter} from './frontMatter';
 
@@ -38,48 +39,6 @@ export function getContentPathList(contentPaths: PagesContentPaths): string[] {
   return [contentPaths.contentPathLocalized, contentPaths.contentPath];
 }
 
-async function getLocalizedSource({
-  relativeSource,
-  contentPaths,
-  locale,
-}: {
-  relativeSource: string;
-  contentPaths: PagesContentPaths;
-  locale: string;
-}) {
-  const {name, dir, ext} = path.parse(relativeSource);
-
-  // Lookup in localized folder in priority
-  const possibleSources = getContentPathList(contentPaths).flatMap(
-    (contentPath) => [
-      path.join(contentPath, dir, `${name}.${locale}${ext}`),
-      path.join(contentPath, relativeSource),
-    ],
-  );
-
-  const localizedSource = await findAsyncSequential(
-    possibleSources,
-    fs.pathExists,
-  );
-
-  if (!localizedSource) {
-    throw new Error('unexpected');
-  }
-
-  return localizedSource;
-}
-
-function filterLocaleExtensionFiles(
-  files: string[],
-  locales: string[],
-): string[] {
-  const localeExtensions = locales.map((locale) => `.${locale}`);
-  return files.filter((file) => {
-    const {name} = path.parse(file);
-    return !localeExtensions.includes(path.extname(name));
-  });
-}
-
 const isMarkdownSource = (source: string) =>
   source.endsWith('.md') || source.endsWith('.mdx');
 
@@ -109,7 +68,10 @@ export default function pluginContentPages(
       cwd: contentPaths.contentPath,
       ignore: options.exclude,
     });
-    return filterLocaleExtensionFiles(files, context.i18n.locales);
+    return filterFilesWithLocaleExtension({
+      files,
+      locales: context.i18n.locales,
+    });
   }
 
   return {
@@ -133,7 +95,7 @@ export default function pluginContentPages(
       async function processPageSourceFile(
         relativeSource: string,
       ): Promise<Metadata | undefined> {
-        const source = await getLocalizedSource({
+        const source = await getLocalizedSourcePath({
           relativeSource,
           contentPaths,
           locale: context.i18n.currentLocale,

packages/docusaurus-utils/src/i18nUtils.ts

@@ -6,14 +6,17 @@
  */
 
 import path from 'path';
+import fs from 'fs-extra';
 import _ from 'lodash';
 import {DEFAULT_PLUGIN_ID} from './constants';
 import {normalizeUrl} from './urlUtils';
+import {findAsyncSequential} from './jsUtils';
 import type {
   TranslationFileContent,
   TranslationFile,
   I18n,
 } from '@docusaurus/types';
+import type {ContentPaths} from './markdownLinks';
 
 /**
  * Takes a list of translation file contents, and shallow-merges them into one.
@@ -112,3 +115,82 @@ export function localizePath({
   // Url paths; add a trailing slash so it's a valid base URL
   return normalizeUrl([originalPath, i18n.currentLocale, '/']);
 }
+
+/**
+ * Localize a content file path
+ * ./dir/myDoc.md => ./dir/myDoc.fr.md
+ * @param filePath
+ * @param locale
+ */
+function addLocaleExtension(filePath: string, locale: string) {
+  const {name, dir, ext} = path.parse(filePath);
+  return path.join(dir, `${name}.${locale}${ext}`);
+}
+
+/**
+ * Returns the first existing localized path of a content file
+ * @param relativeSource
+ * @param contentPaths
+ * @param locale
+ */
+export async function getLocalizedSourcePath({
+  relativeSource,
+  contentPaths,
+  locale,
+}: {
+  relativeSource: string;
+  contentPaths: ContentPaths;
+  locale: string;
+}): Promise<string> {
+  // docs/myDoc.fr.md
+  const localeExtensionSource = path.join(
+    contentPaths.contentPath,
+    addLocaleExtension(relativeSource, locale),
+  );
+
+  // i18n/fr/docs/current/myDoc.md
+  const i18nFolderSource = path.join(
+    contentPaths.contentPathLocalized,
+    relativeSource,
+  );
+
+  // docs/myDoc.md
+  const originalSource = path.join(contentPaths.contentPath, relativeSource);
+
+  // Order matters
+  const possibleSources = [
+    localeExtensionSource,
+    i18nFolderSource,
+    originalSource,
+  ];
+
+  // TODO can we avoid/optimize this by passing all the files we know as param?
+  const localizedSource = await findAsyncSequential(
+    possibleSources,
+    fs.pathExists,
+  );
+
+  if (!localizedSource) {
+    throw new Error(
+      `Unexpected error, couldn't find any existing file at ${originalSource}`,
+    );
+  }
+
+  return localizedSource;
+}
+
+export function filterFilesWithLocaleExtension({
+  files,
+  locales,
+}: {
+  files: string[];
+  locales: string[];
+}): string[] {
+  const possibleLocaleExtensions = new Set(
+    locales.map((locale) => `.${locale}`),
+  );
+  return files.filter((file) => {
+    const {name} = path.parse(file);
+    return !possibleLocaleExtensions.has(path.extname(name));
+  });
+}

packages/docusaurus-utils/src/index.ts

@@ -34,6 +34,8 @@ export {
   updateTranslationFileMessages,
   getPluginI18nPath,
   localizePath,
+  getLocalizedSourcePath,
+  filterFilesWithLocaleExtension,
 } from './i18nUtils';
 export {
   removeSuffix,