@docusaurus/core 2.0.0-beta.fc64c12e4 → 2.0.0

package/lib/server/siteMetadata.js

@@ -0,0 +1,81 @@
+"use strict";
+/**
+ * Copyright (c) Facebook, Inc. and its affiliates.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.loadSiteMetadata = exports.getPluginVersion = void 0;
+const tslib_1 = require("tslib");
+const fs_extra_1 = tslib_1.__importDefault(require("fs-extra"));
+const path_1 = tslib_1.__importDefault(require("path"));
+const logger_1 = tslib_1.__importDefault(require("@docusaurus/logger"));
+const utils_1 = require("@docusaurus/utils");
+async function getPackageJsonVersion(packageJsonPath) {
+    if (await fs_extra_1.default.pathExists(packageJsonPath)) {
+        // eslint-disable-next-line @typescript-eslint/no-var-requires, import/no-dynamic-require, global-require
+        return require(packageJsonPath).version;
+    }
+    return undefined;
+}
+async function getPackageJsonName(packageJsonPath) {
+    // eslint-disable-next-line @typescript-eslint/no-var-requires, import/no-dynamic-require, global-require
+    return require(packageJsonPath).name;
+}
+async function getPluginVersion(pluginPath, siteDir) {
+    let potentialPluginPackageJsonDirectory = path_1.default.dirname(pluginPath);
+    while (potentialPluginPackageJsonDirectory !== '/') {
+        const packageJsonPath = path_1.default.join(potentialPluginPackageJsonDirectory, 'package.json');
+        if ((await fs_extra_1.default.pathExists(packageJsonPath)) &&
+            (await fs_extra_1.default.lstat(packageJsonPath)).isFile()) {
+            if (potentialPluginPackageJsonDirectory === siteDir) {
+                // If the plugin belongs to the same docusaurus project, we classify it
+                // as local plugin.
+                return { type: 'project' };
+            }
+            return {
+                type: 'package',
+                name: await getPackageJsonName(packageJsonPath),
+                version: await getPackageJsonVersion(packageJsonPath),
+            };
+        }
+        potentialPluginPackageJsonDirectory = path_1.default.dirname(potentialPluginPackageJsonDirectory);
+    }
+    // In the case where a plugin is a path where no parent directory contains
+    // package.json, we can only classify it as local. Could happen if one puts a
+    // script in the parent directory of the site.
+    return { type: 'local' };
+}
+exports.getPluginVersion = getPluginVersion;
+/**
+ * We want all `@docusaurus/*` packages to have the exact same version!
+ * @see https://github.com/facebook/docusaurus/issues/3371
+ * @see https://github.com/facebook/docusaurus/pull/3386
+ */
+function checkDocusaurusPackagesVersion(siteMetadata) {
+    const { docusaurusVersion } = siteMetadata;
+    Object.entries(siteMetadata.pluginVersions).forEach(([plugin, versionInfo]) => {
+        if (versionInfo.type === 'package' &&
+            versionInfo.name?.startsWith('@docusaurus/') &&
+            versionInfo.version &&
+            versionInfo.version !== docusaurusVersion) {
+            // Should we throw instead? It still could work with different versions
+            logger_1.default.error `Invalid name=${plugin} version number=${versionInfo.version}.
+All official @docusaurus/* packages should have the exact same version as @docusaurus/core (number=${docusaurusVersion}).
+Maybe you want to check, or regenerate your yarn.lock or package-lock.json file?`;
+        }
+    });
+}
+async function loadSiteMetadata({ plugins, siteDir, }) {
+    const siteMetadata = {
+        docusaurusVersion: utils_1.DOCUSAURUS_VERSION,
+        siteVersion: await getPackageJsonVersion(path_1.default.join(siteDir, 'package.json')),
+        pluginVersions: Object.fromEntries(plugins
+            .filter(({ version: { type } }) => type !== 'synthetic')
+            .map(({ name, version }) => [name, version])),
+    };
+    checkDocusaurusPackagesVersion(siteMetadata);
+    return siteMetadata;
+}
+exports.loadSiteMetadata = loadSiteMetadata;

package/lib/server/translations/translations.d.ts

@@ -1,36 +1,31 @@
-import { TranslationFileContent, TranslationFile, TranslationMessage, InitializedPlugin } from '@docusaurus/types';
+/**
+ * Copyright (c) Facebook, Inc. and its affiliates.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ */
+import type { TranslationFileContent, TranslationFile, CodeTranslations, InitializedPlugin } from '@docusaurus/types';
 export declare type WriteTranslationsOptions = {
     override?: boolean;
     messagePrefix?: string;
 };
 declare type TranslationContext = {
-    siteDir: string;
-    locale: string;
+    localizationDir: string;
 };
-export declare function ensureTranslationFileContent(content: unknown): asserts content is TranslationFileContent;
-export declare function readTranslationFileContent(filePath: string): Promise<TranslationFileContent | undefined>;
-export declare function writeTranslationFileContent({ filePath, content: newContent, options, }: {
-    filePath: string;
-    content: TranslationFileContent;
-    options?: WriteTranslationsOptions;
-}): Promise<void>;
-export declare function getTranslationsDirPath(context: TranslationContext): string;
-export declare function getTranslationsLocaleDirPath(context: TranslationContext): string;
-export declare function getCodeTranslationsFilePath(context: TranslationContext): string;
 export declare function readCodeTranslationFileContent(context: TranslationContext): Promise<TranslationFileContent | undefined>;
 export declare function writeCodeTranslations(context: TranslationContext, content: TranslationFileContent, options: WriteTranslationsOptions): Promise<void>;
-export declare function writePluginTranslations({ siteDir, plugin, locale, translationFile, options, }: TranslationContext & {
+export declare function writePluginTranslations({ localizationDir, plugin, translationFile, options, }: TranslationContext & {
     plugin: InitializedPlugin;
     translationFile: TranslationFile;
     options?: WriteTranslationsOptions;
 }): Promise<void>;
-export declare function localizePluginTranslationFile({ siteDir, plugin, locale, translationFile, }: TranslationContext & {
+export declare function localizePluginTranslationFile({ localizationDir, plugin, translationFile, }: TranslationContext & {
     plugin: InitializedPlugin;
     translationFile: TranslationFile;
 }): Promise<TranslationFile>;
-export declare function getPluginsDefaultCodeTranslationMessages(plugins: InitializedPlugin[]): Promise<Record<string, string>>;
+export declare function getPluginsDefaultCodeTranslationMessages(plugins: InitializedPlugin[]): Promise<CodeTranslations>;
 export declare function applyDefaultCodeTranslations({ extractedCodeTranslations, defaultCodeMessages, }: {
-    extractedCodeTranslations: Record<string, TranslationMessage>;
-    defaultCodeMessages: Record<string, string>;
-}): Record<string, TranslationMessage>;
+    extractedCodeTranslations: TranslationFileContent;
+    defaultCodeMessages: CodeTranslations;
+}): TranslationFileContent;
 export {};

package/lib/server/translations/translations.js

@@ -1,19 +1,19 @@
 "use strict";
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.applyDefaultCodeTranslations = exports.getPluginsDefaultCodeTranslationMessages = exports.localizePluginTranslationFile = exports.writePluginTranslations = exports.writeCodeTranslations = exports.readCodeTranslationFileContent = exports.getCodeTranslationsFilePath = exports.getTranslationsLocaleDirPath = exports.getTranslationsDirPath = exports.writeTranslationFileContent = exports.readTranslationFileContent = exports.ensureTranslationFileContent = void 0;
-const tslib_1 = require("tslib");
 /**
  * Copyright (c) Facebook, Inc. and its affiliates.
  *
  * This source code is licensed under the MIT license found in the
  * LICENSE file in the root directory of this source tree.
  */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.applyDefaultCodeTranslations = exports.getPluginsDefaultCodeTranslationMessages = exports.localizePluginTranslationFile = exports.writePluginTranslations = exports.writeCodeTranslations = exports.readCodeTranslationFileContent = void 0;
+const tslib_1 = require("tslib");
 const path_1 = tslib_1.__importDefault(require("path"));
 const fs_extra_1 = tslib_1.__importDefault(require("fs-extra"));
-const lodash_1 = require("lodash");
+const lodash_1 = tslib_1.__importDefault(require("lodash"));
+const logger_1 = tslib_1.__importDefault(require("@docusaurus/logger"));
 const utils_1 = require("@docusaurus/utils");
 const utils_validation_1 = require("@docusaurus/utils-validation");
-const chalk_1 = tslib_1.__importDefault(require("chalk"));
 const TranslationFileContentSchema = utils_validation_1.Joi.object()
     .pattern(utils_validation_1.Joi.string(), utils_validation_1.Joi.object({
     message: utils_validation_1.Joi.string().allow('').required(),
@@ -27,40 +27,35 @@ function ensureTranslationFileContent(content) {
         convert: false,
     });
 }
-exports.ensureTranslationFileContent = ensureTranslationFileContent;
 async function readTranslationFileContent(filePath) {
     if (await fs_extra_1.default.pathExists(filePath)) {
         try {
-            const content = JSON.parse(await fs_extra_1.default.readFile(filePath, 'utf8'));
+            const content = await fs_extra_1.default.readJSON(filePath);
             ensureTranslationFileContent(content);
             return content;
         }
-        catch (e) {
-            throw new Error(`Invalid translation file at ${filePath}.\n${e.message}`);
+        catch (err) {
+            logger_1.default.error `Invalid translation file at path=${filePath}.`;
+            throw err;
         }
     }
     return undefined;
 }
-exports.readTranslationFileContent = readTranslationFileContent;
 function mergeTranslationFileContent({ existingContent = {}, newContent, options, }) {
     // Apply messagePrefix to all messages
-    const newContentTransformed = lodash_1.mapValues(newContent, (value) => {
-        var _a;
-        return ({
-            ...value,
-            message: `${(_a = options.messagePrefix) !== null && _a !== void 0 ? _a : ''}${value.message}`,
-        });
-    });
+    const newContentTransformed = lodash_1.default.mapValues(newContent, (value) => ({
+        ...value,
+        message: `${options.messagePrefix ?? ''}${value.message}`,
+    }));
     const result = { ...existingContent };
     // We only add missing keys here, we don't delete existing ones
     Object.entries(newContentTransformed).forEach(([key, { message, description }]) => {
-        var _a, _b;
         result[key] = {
-            // If the messages already exist, we don't override them (unless requested)
+            // If messages already exist, we don't override them (unless requested)
             message: options.override
                 ? message
-                : (_b = (_a = existingContent[key]) === null || _a === void 0 ? void 0 : _a.message) !== null && _b !== void 0 ? _b : message,
-            description, // description
+                : existingContent[key]?.message ?? message,
+            description,
         };
     });
     return result;
@@ -68,11 +63,10 @@ function mergeTranslationFileContent({ existingContent = {}, newContent, options
 async function writeTranslationFileContent({ filePath, content: newContent, options = {}, }) {
     const existingContent = await readTranslationFileContent(filePath);
     // Warn about potential legacy keys
-    const unknownKeys = lodash_1.difference(Object.keys(existingContent !== null && existingContent !== void 0 ? existingContent : {}), Object.keys(newContent));
+    const unknownKeys = lodash_1.default.difference(Object.keys(existingContent ?? {}), Object.keys(newContent));
     if (unknownKeys.length > 0) {
-        console.warn(chalk_1.default.yellow(`Some translation keys looks unknown to us in file ${filePath}
-Maybe you should remove them?
-- ${unknownKeys.join('\n- ')}`));
+        logger_1.default.warn `Some translation keys looks unknown to us in file path=${filePath}.
+Maybe you should remove them? ${unknownKeys}`;
     }
     const mergedContent = mergeTranslationFileContent({
         existingContent,
@@ -81,27 +75,13 @@ Maybe you should remove them?
     });
     // Avoid creating empty translation files
     if (Object.keys(mergedContent).length > 0) {
-        console.log(`${Object.keys(mergedContent)
-            .length.toString()
-            .padStart(3, ' ')} translations will be written at "${utils_1.toMessageRelativeFilePath(filePath)}".`);
-        await fs_extra_1.default.ensureDir(path_1.default.dirname(filePath));
-        await fs_extra_1.default.writeFile(filePath, JSON.stringify(mergedContent, null, 2));
+        logger_1.default.info `number=${Object.keys(mergedContent).length} translations will be written at path=${(0, utils_1.toMessageRelativeFilePath)(filePath)}.`;
+        await fs_extra_1.default.outputFile(filePath, `${JSON.stringify(mergedContent, null, 2)}\n`);
     }
 }
-exports.writeTranslationFileContent = writeTranslationFileContent;
-// should we make this configurable?
-function getTranslationsDirPath(context) {
-    return path_1.default.resolve(path_1.default.join(context.siteDir, `i18n`));
-}
-exports.getTranslationsDirPath = getTranslationsDirPath;
-function getTranslationsLocaleDirPath(context) {
-    return path_1.default.join(getTranslationsDirPath(context), context.locale);
-}
-exports.getTranslationsLocaleDirPath = getTranslationsLocaleDirPath;
 function getCodeTranslationsFilePath(context) {
-    return path_1.default.join(getTranslationsLocaleDirPath(context), 'code.json');
+    return path_1.default.join(context.localizationDir, utils_1.CODE_TRANSLATIONS_FILE_NAME);
 }
-exports.getCodeTranslationsFilePath = getCodeTranslationsFilePath;
 async function readCodeTranslationFileContent(context) {
     return readTranslationFileContent(getCodeTranslationsFilePath(context));
 }
@@ -123,21 +103,19 @@ function addTranslationFileExtension(translationFilePath) {
     }
     return `${translationFilePath}.json`;
 }
-function getPluginTranslationFilePath({ siteDir, plugin, locale, translationFilePath, }) {
-    const dirPath = utils_1.getPluginI18nPath({
-        siteDir,
-        locale,
+function getPluginTranslationFilePath({ localizationDir, plugin, translationFilePath, }) {
+    const dirPath = (0, utils_1.getPluginI18nPath)({
+        localizationDir,
         pluginName: plugin.name,
         pluginId: plugin.options.id,
     });
     const filePath = addTranslationFileExtension(translationFilePath);
     return path_1.default.join(dirPath, filePath);
 }
-async function writePluginTranslations({ siteDir, plugin, locale, translationFile, options, }) {
+async function writePluginTranslations({ localizationDir, plugin, translationFile, options, }) {
     const filePath = getPluginTranslationFilePath({
         plugin,
-        siteDir,
-        locale,
+        localizationDir,
         translationFilePath: translationFile.path,
     });
     await writeTranslationFileContent({
@@ -147,16 +125,15 @@ async function writePluginTranslations({ siteDir, plugin, locale, translationFil
     });
 }
 exports.writePluginTranslations = writePluginTranslations;
-async function localizePluginTranslationFile({ siteDir, plugin, locale, translationFile, }) {
+async function localizePluginTranslationFile({ localizationDir, plugin, translationFile, }) {
     const filePath = getPluginTranslationFilePath({
         plugin,
-        siteDir,
-        locale,
+        localizationDir,
         translationFilePath: translationFile.path,
     });
     const localizedContent = await readTranslationFileContent(filePath);
     if (localizedContent) {
-        // localized messages "override" default unlocalized messages
+        // Localized messages "override" default unlocalized messages
         return {
             path: translationFile.path,
             content: {
@@ -165,32 +142,23 @@ async function localizePluginTranslationFile({ siteDir, plugin, locale, translat
             },
         };
     }
-    else {
-        return translationFile;
-    }
+    return translationFile;
 }
 exports.localizePluginTranslationFile = localizePluginTranslationFile;
 async function getPluginsDefaultCodeTranslationMessages(plugins) {
-    const pluginsMessages = await Promise.all(plugins.map((plugin) => { var _a, _b; return (_b = (_a = plugin.getDefaultCodeTranslationMessages) === null || _a === void 0 ? void 0 : _a.call(plugin)) !== null && _b !== void 0 ? _b : {}; }));
-    return pluginsMessages.reduce((allMessages, pluginMessages) => {
-        return { ...allMessages, ...pluginMessages };
-    }, {});
+    const pluginsMessages = await Promise.all(plugins.map((plugin) => plugin.getDefaultCodeTranslationMessages?.() ?? {}));
+    return pluginsMessages.reduce((allMessages, pluginMessages) => ({ ...allMessages, ...pluginMessages }), {});
 }
 exports.getPluginsDefaultCodeTranslationMessages = getPluginsDefaultCodeTranslationMessages;
 function applyDefaultCodeTranslations({ extractedCodeTranslations, defaultCodeMessages, }) {
-    const unusedDefaultCodeMessages = lodash_1.difference(Object.keys(defaultCodeMessages), Object.keys(extractedCodeTranslations));
+    const unusedDefaultCodeMessages = lodash_1.default.difference(Object.keys(defaultCodeMessages), Object.keys(extractedCodeTranslations));
     if (unusedDefaultCodeMessages.length > 0) {
-        console.warn(chalk_1.default.yellow(`Unused default message codes found.
-Please report this Docusaurus issue.
-- ${unusedDefaultCodeMessages.join('\n- ')}
-`));
+        logger_1.default.warn `Unused default message codes found.
+Please report this Docusaurus issue. name=${unusedDefaultCodeMessages}`;
     }
-    return lodash_1.mapValues(extractedCodeTranslations, (messageTranslation, messageId) => {
-        var _a;
-        return {
-            ...messageTranslation,
-            message: (_a = defaultCodeMessages[messageId]) !== null && _a !== void 0 ? _a : messageTranslation.message,
-        };
-    });
+    return lodash_1.default.mapValues(extractedCodeTranslations, (messageTranslation, messageId) => ({
+        ...messageTranslation,
+        message: defaultCodeMessages[messageId] ?? messageTranslation.message,
+    }));
 }
 exports.applyDefaultCodeTranslations = applyDefaultCodeTranslations;

package/lib/server/translations/translationsExtractor.d.ts

@@ -1,10 +1,16 @@
-import { TransformOptions } from '@babel/core';
-import { InitializedPlugin, TranslationFileContent, TranslationMessage } from '@docusaurus/types';
+/**
+ * Copyright (c) Facebook, Inc. and its affiliates.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ */
+import { type TransformOptions } from '@babel/core';
+import type { InitializedPlugin, TranslationFileContent } from '@docusaurus/types';
 export declare function globSourceCodeFilePaths(dirPaths: string[]): Promise<string[]>;
-export declare function extractSiteSourceCodeTranslations(siteDir: string, plugins: InitializedPlugin[], babelOptions: TransformOptions): Promise<TranslationFileContent>;
+export declare function extractSiteSourceCodeTranslations(siteDir: string, plugins: InitializedPlugin[], babelOptions: TransformOptions, extraSourceCodeFilePaths?: string[]): Promise<TranslationFileContent>;
 declare type SourceCodeFileTranslations = {
     sourceCodeFilePath: string;
-    translations: Record<string, TranslationMessage>;
+    translations: TranslationFileContent;
     warnings: string[];
 };
 export declare function extractAllSourceCodeFileTranslations(sourceCodeFilePaths: string[], babelOptions: TransformOptions): Promise<SourceCodeFileTranslations[]>;