{"record":{"id":"36a2dca4162e3f71","repo":"facebook/docusaurus","slug":"error-while-attempting-to-extract-docusaurus-trans","errorCode":null,"errorMessage":"Error while attempting to extract Docusaurus translations from source code file at path=${sourceCodeFilePath}.","messagePattern":"Error while attempting to extract Docusaurus translations from source code file at path=(.+?)\\.","errorType":"exception","errorClass":"Error","httpStatus":null,"severity":"error","filePath":"packages/docusaurus-babel/src/babelTranslationsExtractor.ts","lineNumber":59,"sourceCode":"  try {\n    const code = await fs.readFile(sourceCodeFilePath, 'utf8');\n\n    const ast = parse(code, {\n      ...babelOptions,\n      ast: true,\n      // filename is important, because babel does not process the same files\n      // according to their js/ts extensions.\n      // See https://x.com/NicoloRibaudo/status/1321130735605002243\n      filename: sourceCodeFilePath,\n    }) as Node;\n\n    const translations = extractSourceCodeAstTranslations(\n      ast,\n      sourceCodeFilePath,\n    );\n    return translations;\n  } catch (err) {\n    throw new Error(\n      logger.interpolate`Error while attempting to extract Docusaurus translations from source code file at path=${sourceCodeFilePath}.`,\n      {cause: err},\n    );\n  }\n}\n\n/*\nNeed help understanding this?\n\nUseful resources:\nhttps://github.com/jamiebuilds/babel-handbook/blob/master/translations/en/plugin-handbook.md\nhttps://github.com/formatjs/formatjs/blob/main/packages/babel-plugin-formatjs/index.ts\nhttps://github.com/pugjs/babel-walk\n */\nfunction extractSourceCodeAstTranslations(\n  ast: Node,\n  sourceCodeFilePath: string,\n): SourceCodeFileTranslations {","sourceCodeStart":41,"sourceCodeEnd":77,"githubUrl":"https://github.com/facebook/docusaurus/blob/3f483e80e326cc646b54b83d564b3f0c4881b9a6/packages/docusaurus-babel/src/babelTranslationsExtractor.ts#L41-L77","documentation":"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`.","triggerScenarios":"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.","commonSituations":"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.","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."],"exampleFix":"// before: file uses the satisfies operator but @babel/preset-typescript is too old\nconst x: Foo = {…} satisfies Foo;\n// after: upgrade @babel/preset-typescript, or remove the unsupported syntax","handlingStrategy":"try-catch","validationCode":"import fs from 'node:fs/promises';\nasync function isParsable(filePath: string): Promise<boolean> {\n  try { JSON.parse(await fs.readFile(filePath, 'utf8')); return true; } catch { return false; }\n}\n// for source files: validate they are text and within the project src/ dir","typeGuard":null,"tryCatchPattern":"try {\n  await extractSourceCodeFileTranslations(file, babelOptions);\n} catch (err) {\n  if (/extract Docusaurus translations/.test((err as Error).message)) {\n    logger.warn(`Skipping translation extraction for ${file}: ${(err as Error & {cause?: Error}).cause?.message}`);\n    return null;\n  }\n  throw err;\n}","preventionTips":["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."],"tags":["babel","translations","i18n","parsing","wrapped-error"],"backgroundTag":null,"analyzedSha":"3f483e80e326cc646b54b83d564b3f0c4881b9a6","analyzedAt":"2026-08-12T13:25:04.382Z","schemaVersion":2},"datasetVersion":"2026-08-12T18:17:37.767Z"}