Please make sure all theme translations are static! Some war

Error message

Please make sure all theme translations are static!
Some warnings were found!

${fileExtractedTranslations.warnings.join('\n\n')}

What it means

Thrown by extractThemeCodeMessages in docusaurus-theme-translations when the Babel-based translation extractor (extractAllSourceCodeFileTranslations) emits warnings for any source file. Docusaurus theme translations must be statically analyzable (literal translate() calls) so they can be extracted for localization; dynamic/generated message keys break extraction. Used by the update.mjs maintenance script and tests, not at runtime.

Source

Thrown at packages/docusaurus-theme-translations/src/utils.ts:75

  targetDirs?: string[],
): Promise<TranslationFileContent> {
  // eslint-disable-next-line no-param-reassign
  targetDirs ??= (await getThemes()).flatMap((theme) => theme.src);

  const filePaths = (await globTranslatableSourceFiles(targetDirs)).filter(
    (filePath) => ['.js', '.jsx'].includes(path.extname(filePath)),
  );

  const filesExtractedTranslations = await extractAllSourceCodeFileTranslations(
    filePaths,
    {
      presets: [require.resolve('@docusaurus/babel/preset')],
    },
  );

  filesExtractedTranslations.forEach((fileExtractedTranslations) => {
    if (fileExtractedTranslations.warnings.length > 0) {
      throw new Error(`Please make sure all theme translations are static!
Some warnings were found!

${fileExtractedTranslations.warnings.join('\n\n')}
`);
    }
  });

  const translations = filesExtractedTranslations.reduce(
    (acc, extractedTranslations) => ({
      ...acc,
      ...extractedTranslations.translations,
    }),
    {},
  );

  return translations;
}

View on GitHub (pinned to 3f483e80e3)

Solutions

Read the warnings printed in the error to find the offending file(s) and translate() usages.
Refactor those usages to static message keys (string literals, no interpolation in the key).
Re-run the update script (pnpm update:codeTranslations or the theme-translations update.mjs).
If a usage is intentionally dynamic, restructure to use a static key with parameters.

Example fix

// before (non-static key)
const t = translate({ message: `Hello ${name}` });
// after (static key, dynamic param)
const t = translate(
  { message: 'Hello {name}' },
  { name },
);

Defensive patterns

Strategy: try-catch

Try / catch

try {
  await extractThemeCodeMessages(targetDirs);
} catch (err) {
  // err.message contains the per-file warnings; fix each translate() call,
  // then re-run the extraction script.
  console.error(err.message);
  process.exit(1);
}

Prevention

Always use static string-literal message keys in translate()/interpolate().
Run the theme-translations extraction in CI for theme packages so dynamic-key regressions fail the build.
Avoid composing translation keys at runtime; pass parameters instead.

When it happens

Trigger: Running the theme-translations update script (or its tests) against theme source that contains non-static translate usages: computed keys, template literals with expressions, function-wrapped messages, or unsupported babel patterns. Each file's warnings are aggregated and, if non-empty, the whole extraction aborts.

Common situations: Editing theme components (theme-classic, theme-common, theme-search-algolia) to use dynamic translation keys; introducing interpolate/translate calls the extractor can't statically resolve; refactoring that breaks the @docusaurus/babel preset extraction.

Related errors

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