website/docs/api/plugin-methods/i18n-lifecycles.mdx - main - githubmirror/docusaurus

website/docs/api/plugin-methods/i18n-lifecycles.mdx
121 строка3 KB
Sébastien Lorber
chore(website): migrate MDX heading ids to comment syntax + upgrade Crowdin parser version (#11779)
06 мар 2026, 23:48
06 мар 2026, 23:48caff1c4
---
sidebar_position: 3
---

# I18n lifecycles

Plugins use these lifecycles to load i18n-related data.

## `getTranslationFiles({content})` {/* #getTranslationFiles */}

Plugins declare the JSON translation files they want to use.

Returns translation files `{path: string, content: ChromeI18nJSON}`:

- `path`: relative to the plugin localized folder `i18n/[locale]/[pluginName]`. Extension `.json` should be omitted to remain generic.
- `content`: using the Chrome i18n JSON format.

These files will be written by the [`write-translations` CLI](../../cli.mdx#docusaurus-write-translations-sitedir) to the plugin i18n subfolder, and will be read in the appropriate locale before calling [`translateContent()`](#translateContent) and [`translateThemeConfig()`](#translateThemeConfig)

Example:

```js title="my-plugin.js"
export default function (context, options) {
  return {
    name: 'my-plugin',
    // highlight-start
    async getTranslationFiles({content}) {
      return [
        {
          path: 'sidebar-labels',
          content: {
            someSidebarLabel: {
              message: 'Some Sidebar Label',
              description: 'A label used in my plugin in the sidebar',
            },
            someLabelFromContent: content.myLabel,
          },
        },
      ];
    },
    // highlight-end
  };
}
```

## `translateContent({content,translationFiles})` {/* #translateContent */}

Translate the plugin content, using the localized translation files.

Returns the localized plugin content.

The `contentLoaded()` lifecycle will be called with the localized plugin content returned by `translateContent()`.

Example:

```js title="my-plugin.js"
export default function (context, options) {
  return {
    name: 'my-plugin',
    // highlight-start
    translateContent({content, translationFiles}) {
      const myTranslationFile = translationFiles.find(
        (f) => f.path === 'myTranslationFile',
      );
      return {
        ...content,
        someContentLabel: myTranslationFile.someContentLabel.message,
      };
    },
    // highlight-end
  };
}
```

## `translateThemeConfig({themeConfig,translationFiles})` {/* #translateThemeConfig */}

Translate the site `themeConfig` labels, using the localized translation files.

Returns the localized `themeConfig`.

Example:

```js title="my-plugin.js"
export default function (context, options) {
  return {
    name: 'my-theme',
    // highlight-start
    translateThemeConfig({themeConfig, translationFiles}) {
      const myTranslationFile = translationFiles.find(
        (f) => f.path === 'myTranslationFile',
      );
      return {
        ...themeConfig,
        someThemeConfigLabel: myTranslationFile.someThemeConfigLabel.message,
      };
    },
    // highlight-end
  };
}
```

## `async getDefaultCodeTranslationMessages()` {/* #getDefaultCodeTranslationMessages */}

Themes using the `<Translate>` API can provide default code translation messages.

It should return messages in `Record<string, string>`, where keys are translation IDs and values are messages (without the description) localized using the site's current locale.

Example:

```js title="my-plugin.js"
export default function (context, options) {
  return {
    name: 'my-theme',
    // highlight-start
    async getDefaultCodeTranslationMessages() {
      return readJsonFile(`${context.i18n.currentLocale}.json`);
    },
    // highlight-end
  };
}
```