facebook/docusaurus · error · Error

Error while attempting to extract Docusaurus translations fr

Error message

Error while attempting to extract Docusaurus translations from source code file at path=${sourceCodeFilePath}.

What it means

Thrown by extractSourceCodeFileTranslations() in @docusaurus/babel when Babel fails to parse or traverse a source file during the `docusaurus write-translations` command. The file is read, parsed with the site's babel config, then AST-traversed to find translate() / <Translate> usages; any failure is wrapped with the file path and the original error as `cause`.

Source

Thrown at packages/docusaurus-babel/src/babelTranslationsExtractor.ts:59

  try {
    const code = await fs.readFile(sourceCodeFilePath, 'utf8');

    const ast = parse(code, {
      ...babelOptions,
      ast: true,
      // filename is important, because babel does not process the same files
      // according to their js/ts extensions.
      // See https://x.com/NicoloRibaudo/status/1321130735605002243
      filename: sourceCodeFilePath,
    }) as Node;

    const translations = extractSourceCodeAstTranslations(
      ast,
      sourceCodeFilePath,
    );
    return translations;
  } catch (err) {
    throw new Error(
      logger.interpolate`Error while attempting to extract Docusaurus translations from source code file at path=${sourceCodeFilePath}.`,
      {cause: err},
    );
  }
}

/*
Need help understanding this?

Useful resources:
https://github.com/jamiebuilds/babel-handbook/blob/master/translations/en/plugin-handbook.md
https://github.com/formatjs/formatjs/blob/main/packages/babel-plugin-formatjs/index.ts
https://github.com/pugjs/babel-walk
 */
function extractSourceCodeAstTranslations(
  ast: Node,
  sourceCodeFilePath: string,
): SourceCodeFileTranslations {

View on GitHub (pinned to 3f483e80e3)

Solutions

Read err.cause to see the exact babel parse error and offending line in the named sourceCodeFilePath.
Fix or temporarily exclude the offending file from the translation extraction source list.
Ensure your babel.config.js includes the required presets (@babel/preset-typescript, @babel/preset-react).
After an upgrade, align @babel/* versions with the ones Docusaurus pins.

Example fix

// before: file uses the satisfies operator but @babel/preset-typescript is too old
const x: Foo = {…} satisfies Foo;
// after: upgrade @babel/preset-typescript, or remove the unsupported syntax

Defensive patterns

Strategy: try-catch

Validate before calling

import fs from 'node:fs/promises';
async function isParsable(filePath: string): Promise<boolean> {
  try { JSON.parse(await fs.readFile(filePath, 'utf8')); return true; } catch { return false; }
}
// for source files: validate they are text and within the project src/ dir

Try / catch

try {
  await extractSourceCodeFileTranslations(file, babelOptions);
} catch (err) {
  if (/extract Docusaurus translations/.test((err as Error).message)) {
    logger.warn(`Skipping translation extraction for ${file}: ${(err as Error & {cause?: Error}).cause?.message}`);
    return null;
  }
  throw err;
}

Prevention

Keep babel.config.js presets aligned with the TS/JSX features you use.
Exclude non-source files from the translation extraction list.
After upgrading @babel/core, re-run write-translations in CI to catch regressions.

When it happens

Trigger: Running `docusaurus write-translations` against a source file with syntax the configured babel cannot parse; a file with TypeScript/JSX that requires a preset not in the babel config; a corrupted or binary file mistakenly included in the sourceCodeFilePaths list; a babel config regression after an upgrade.

Common situations: Upgrading Docusaurus or @babel/core and hitting a parser incompatibility; importing a file written for a newer TS syntax than @babel/preset-typescript supports; a plugin adding a non-JS file to the translation source list; custom babel config that drops a needed preset.

Related errors

AI-assisted analysis of facebook/docusaurus@3f483e80e3 (2026-08-12). Data as JSON: /api/errors/36a2dca4162e3f71. Report an issue: GitHub.