facebook/docusaurus · error · Error

Can't write-translation for locale "${locale}" that is not i

Error message

Can't write-translation for locale "${locale}" that is not in the locale configuration file.\nAvailable locales are: ${context.i18n.locales.join(',')}.

What it means

Thrown by `writeTranslations` when the requested `--locale` is not present in `context.i18n.locales` (the locales declared in the site's i18n config). Docusaurus will not extract/write translation files for a locale the site does not officially support.

Source

Thrown at packages/docusaurus/src/commands/writeTranslations.ts:97

export async function writeTranslations(
  siteDirParam: string = '.',
  options: Partial<WriteTranslationsCLIOptions> = {},
): Promise<void> {
  const siteDir = await fs.realpath(siteDirParam);

  const context = await loadContext({
    siteDir,
    config: options.config,
    locale: options.locale,
  });
  const {localizationDir} = context;
  const plugins = await initPlugins(context);

  const locale = options.locale ?? context.i18n.defaultLocale;

  if (!context.i18n.locales.includes(locale)) {
    throw new Error(
      `Can't write-translation for locale "${locale}" that is not in the locale configuration file.
Available locales are: ${context.i18n.locales.join(',')}.`,
    );
  }

  const extractedCodeTranslations = await extractSiteSourceCodeTranslations({
    siteDir,
    plugins,
    extraSourceCodeFilePaths: await getExtraSourceCodeFilePaths(),
  });

  const defaultCodeMessages =
    await loadPluginsDefaultCodeTranslationMessages(plugins);

  const codeTranslations = applyDefaultCodeTranslations({
    extractedCodeTranslations,
    defaultCodeMessages,
  });

View on GitHub (pinned to 3f483e80e3)

Solutions

1. Add the locale to `i18n.locales` in `docusaurus.config.js` before running write-translations.
2. Check the locale code spelling/casing against the configured list (the error prints the available locales).
3. Run without `--locale` to use the default locale, if that is what you intended.
4. Re-run `docusaurus write-translations --locale=<x>` after fixing config — the available-locales list in the message confirms the fix.

Example fix

// before
export default { i18n: { defaultLocale: 'en', locales: ['en'] } };
// docusaurus write-translations --locale=fr  -> throws
// after
export default { i18n: { defaultLocale: 'en', locales: ['en', 'fr'] } };

const locale = options.locale ?? context.i18n.defaultLocale;
if (!context.i18n.locales.includes(locale)) {
  throw new Error(`Locale ${locale} not in i18n.locales: ${context.i18n.locales.join(',')}`);
}

function isConfiguredLocale(locale: string, configured: string[]): locale is string {
  return configured.includes(locale);
}

When it happens

Trigger: Running `docusaurus write-translations --locale=<x>` where `<x>` is neither in `i18n.locales` nor the default locale. Also fires if `options.locale` is omitted but `context.i18n.defaultLocale` itself is not in `locales` (misconfigured i18n).

Common situations: Typo in locale code (e.g. `en-US` vs `en`); forgot to add the locale to `i18n.locales` before translating; copying a command from a project that supports a different locale set; locale casing mismatch.

Related errors

• Unexpected "reportingSeverity" value: ${reportingSeverity}.
• ${JSON.stringify(redirect)} => Validation error: ${error.mes
• Invalid sidebars file. The document with id "${docId}" was u
• No tags file '${relativeFilePath}' could be found in any of
• Can't find locale config for locale ${logger.code(localeToLo

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