chore: release Docusaurus 3.3.0 + 3.3.1 + 3.3.2 (#10101)

website/versioned_docs/version-3.3.2/api/plugin-methods/i18n-lifecycles.mdx

@@ -0,0 +1,121 @@
+---
+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
+  };
+}
+```