feat(core): allow customizing the i18n directory path

packages/docusaurus-plugin-content-blog/src/__tests__/feed.test.ts

@@ -19,6 +19,7 @@ const DefaultI18N: I18n = {
   currentLocale: 'en',
   locales: ['en'],
   defaultLocale: 'en',
+  path: '1i8n',
   localeConfigs: {
     en: {
       label: 'English',

packages/docusaurus-plugin-content-blog/src/__tests__/index.test.ts

@@ -47,6 +47,7 @@ function getI18n(locale: string): I18n {
     currentLocale: locale,
     locales: [locale],
     defaultLocale: locale,
+    path: 'i18n',
     localeConfigs: {
       [locale]: {
         calendar: 'gregory',
@@ -70,6 +71,7 @@ const getPlugin = async (
   i18n: I18n = DefaultI18N,
 ) => {
   const generatedFilesDir: string = path.resolve(siteDir, '.docusaurus');
+  const localizationDir = path.join(siteDir, i18n.path, i18n.currentLocale);
   const siteConfig = {
     title: 'Hello',
     baseUrl: '/',
@@ -81,6 +83,7 @@ const getPlugin = async (
       siteConfig,
       generatedFilesDir,
       i18n,
+      localizationDir,
     } as LoadContext,
     validateOptions({
       validate: normalizePluginOptions as Validate<

packages/docusaurus-plugin-content-blog/src/index.ts

@@ -59,15 +59,15 @@ export default async function pluginContentBlog(
     siteDir,
     siteConfig,
     generatedFilesDir,
+    localizationDir,
     i18n: {currentLocale},
   } = context;
   const {onBrokenMarkdownLinks, baseUrl} = siteConfig;
 
   const contentPaths: BlogContentPaths = {
     contentPath: path.resolve(siteDir, options.path),
     contentPathLocalized: getPluginI18nPath({
-      siteDir,
-      locale: currentLocale,
+      localizationDir,
       pluginName: 'docusaurus-plugin-content-blog',
       pluginId: options.id,
     }),

packages/docusaurus-plugin-content-docs/src/cli.ts

@@ -85,13 +85,15 @@ export async function cliDocsVersionCommand(
 
   await Promise.all(
     i18n.locales.map(async (locale) => {
+      // TODO duplicated logic from core, so duplicate comment as well: we need
+      // to support customization per-locale in the future
+      const localizationDir = path.resolve(siteDir, i18n.path, locale);
       // Copy docs files.
       const docsDir =
         locale === i18n.defaultLocale
           ? path.resolve(siteDir, docsPath)
           : getDocsDirPathLocalized({
-              siteDir,
-              locale,
+              localizationDir,
               pluginId,
               versionName: CURRENT_VERSION_NAME,
             });
@@ -114,8 +116,7 @@ export async function cliDocsVersionCommand(
         locale === i18n.defaultLocale
           ? getVersionDocsDirPath(siteDir, pluginId, version)
           : getDocsDirPathLocalized({
-              siteDir,
-              locale,
+              localizationDir,
               pluginId,
               versionName: version,
             });

packages/docusaurus-plugin-content-docs/src/versions/__tests__/index.test.ts

@@ -17,6 +17,7 @@ import type {
 } from '@docusaurus/plugin-content-docs';
 
 const DefaultI18N: I18n = {
+  path: 'i18n',
   currentLocale: 'en',
   locales: ['en'],
   defaultLocale: 'en',
@@ -37,6 +38,7 @@ describe('readVersionsMetadata', () => {
         siteDir: simpleSiteDir,
         baseUrl: '/',
         i18n: DefaultI18N,
+        localizationDir: path.join(simpleSiteDir, 'i18n/en'),
       } as LoadContext;
 
       const vCurrent: VersionMetadata = {
@@ -198,6 +200,7 @@ describe('readVersionsMetadata', () => {
         siteDir: versionedSiteDir,
         baseUrl: '/',
         i18n: DefaultI18N,
+        localizationDir: path.join(versionedSiteDir, 'i18n/en'),
       } as LoadContext;
 
       const vCurrent: VersionMetadata = {
@@ -636,6 +639,7 @@ describe('readVersionsMetadata', () => {
         siteDir: versionedSiteDir,
         baseUrl: '/',
         i18n: DefaultI18N,
+        localizationDir: path.join(versionedSiteDir, 'i18n/en'),
       } as LoadContext;
 
       const vCurrent: VersionMetadata = {

packages/docusaurus-plugin-content-docs/src/versions/files.ts

@@ -55,19 +55,16 @@ export function getVersionSidebarsPath(
 }
 
 export function getDocsDirPathLocalized({
-  siteDir,
-  locale,
+  localizationDir,
   pluginId,
   versionName,
 }: {
-  siteDir: string;
-  locale: string;
+  localizationDir: string;
   pluginId: string;
   versionName: string;
 }): string {
   return getPluginI18nPath({
-    siteDir,
-    locale,
+    localizationDir,
     pluginName: 'docusaurus-plugin-content-docs',
     pluginId,
     subPaths: [
@@ -175,8 +172,7 @@ export async function getVersionMetadataPaths({
 > {
   const isCurrent = versionName === CURRENT_VERSION_NAME;
   const contentPathLocalized = getDocsDirPathLocalized({
-    siteDir: context.siteDir,
-    locale: context.i18n.currentLocale,
+    localizationDir: context.localizationDir,
     pluginId: options.id,
     versionName,
   });

packages/docusaurus-plugin-content-docs/src/versions/index.ts

@@ -49,8 +49,7 @@ function getVersionEditUrls({
   const editDirPath = options.editCurrentVersion ? options.path : contentPath;
   const editDirPathLocalized = options.editCurrentVersion
     ? getDocsDirPathLocalized({
-        siteDir: context.siteDir,
-        locale: context.i18n.currentLocale,
+        localizationDir: context.localizationDir,
         versionName: CURRENT_VERSION_NAME,
         pluginId: options.id,
       })

packages/docusaurus-plugin-content-pages/src/__tests__/__snapshots__/index.test.ts.snap

@@ -55,19 +55,19 @@ exports[`docusaurus-plugin-content-pages loads simple pages 1`] = `
 exports[`docusaurus-plugin-content-pages loads simple pages with french translations 1`] = `
 [
   {
-    "permalink": "/",
+    "permalink": "/fr/",
     "source": "@site/src/pages/index.js",
     "type": "jsx",
   },
   {
-    "permalink": "/typescript",
+    "permalink": "/fr/typescript",
     "source": "@site/src/pages/typescript.tsx",
     "type": "jsx",
   },
   {
     "description": "Markdown index page",
     "frontMatter": {},
-    "permalink": "/hello/",
+    "permalink": "/fr/hello/",
     "source": "@site/src/pages/hello/index.md",
     "title": "Index",
     "type": "mdx",
@@ -78,26 +78,26 @@ exports[`docusaurus-plugin-content-pages loads simple pages with french translat
       "description": "my mdx page",
       "title": "mdx page",
     },
-    "permalink": "/hello/mdxPage",
+    "permalink": "/fr/hello/mdxPage",
     "source": "@site/src/pages/hello/mdxPage.mdx",
     "title": "mdx page",
     "type": "mdx",
   },
   {
-    "permalink": "/hello/translatedJs",
+    "permalink": "/fr/hello/translatedJs",
     "source": "@site/i18n/fr/docusaurus-plugin-content-pages/hello/translatedJs.js",
     "type": "jsx",
   },
   {
     "description": "translated markdown page (fr)",
     "frontMatter": {},
-    "permalink": "/hello/translatedMd",
+    "permalink": "/fr/hello/translatedMd",
     "source": "@site/i18n/fr/docusaurus-plugin-content-pages/hello/translatedMd.md",
     "title": undefined,
     "type": "mdx",
   },
   {
-    "permalink": "/hello/world",
+    "permalink": "/fr/hello/world",
     "source": "@site/src/pages/hello/world.js",
     "type": "jsx",
   },

packages/docusaurus-plugin-content-pages/src/__tests__/index.test.ts

@@ -32,15 +32,9 @@ describe('docusaurus-plugin-content-pages', () => {
 
   it('loads simple pages with french translations', async () => {
     const siteDir = path.join(__dirname, '__fixtures__', 'website');
-    const context = await loadContext({siteDir});
+    const context = await loadContext({siteDir, locale: 'fr'});
     const plugin = pluginContentPages(
-      {
-        ...context,
-        i18n: {
-          ...context.i18n,
-          currentLocale: 'fr',
-        },
-      },
+      context,
       validateOptions({
         validate: normalizePluginOptions,
         options: {

packages/docusaurus-plugin-content-pages/src/index.ts

@@ -48,18 +48,12 @@ export default function pluginContentPages(
       [admonitions, options.admonitions],
     ]);
   }
-  const {
-    siteConfig,
-    siteDir,
-    generatedFilesDir,
-    i18n: {currentLocale},
-  } = context;
+  const {siteConfig, siteDir, generatedFilesDir, localizationDir} = context;
 
   const contentPaths: PagesContentPaths = {
     contentPath: path.resolve(siteDir, options.path),
     contentPathLocalized: getPluginI18nPath({
-      siteDir,
-      locale: currentLocale,
+      localizationDir,
       pluginName: 'docusaurus-plugin-content-pages',
       pluginId: options.id,
     }),

packages/docusaurus-types/src/index.d.ts

@@ -70,6 +70,11 @@ export type I18nConfig = {
    * 3. Will be used for the `<link hrefLang="x-default">` tag
    */
   defaultLocale: string;
+  /**
+   * Root folder which all locale folders are relative to. Can be absolute or
+   * relative to the config file. e.g. `i18n`
+   */
+  path: string;
   /** List of locales deployed on your site. Must contain `defaultLocale`. */
   locales: [string, ...string[]];
   /** Individual options for each locale. */
@@ -416,6 +421,12 @@ export type LoadContext = {
   siteConfig: DocusaurusConfig;
   siteConfigPath: string;
   outDir: string;
+  /**
+   * Directory where all source translations for the current locale can be found
+   * in. Constructed with `i18n.path` + `i18n.currentLocale.path` (e.g.
+   * `<siteDir>/i18n/en`)
+   */
+  localizationDir: string;
   /**
    * Duplicated from `siteConfig.baseUrl`, but probably worth keeping. We mutate
    * `siteConfig` to make `baseUrl` there localized as well, but that's mostly

packages/docusaurus-utils/src/__tests__/i18nUtils.test.ts

@@ -65,34 +65,33 @@ describe('getPluginI18nPath', () => {
   it('gets correct path', () => {
     expect(
       getPluginI18nPath({
-        siteDir: __dirname,
-        locale: 'zh-Hans',
+        localizationDir: '<SITE_DIR>/i18n/zh-Hans',
         pluginName: 'plugin-content-docs',
         pluginId: 'community',
         subPaths: ['foo'],
       }),
     ).toMatchInlineSnapshot(
-      `"<PROJECT_ROOT>/packages/docusaurus-utils/src/__tests__/i18n/zh-Hans/plugin-content-docs-community/foo"`,
+      `"<SITE_DIR>/i18n/zh-Hans/plugin-content-docs-community/foo"`,
     );
   });
   it('gets correct path for default plugin', () => {
     expect(
       getPluginI18nPath({
-        siteDir: __dirname,
-        locale: 'zh-Hans',
+        localizationDir: '<SITE_DIR>/i18n/zh-Hans',
         pluginName: 'plugin-content-docs',
         subPaths: ['foo'],
-      }).replace(__dirname, ''),
-    ).toMatchInlineSnapshot(`"/i18n/zh-Hans/plugin-content-docs/foo"`);
+      }),
+    ).toMatchInlineSnapshot(
+      `"<SITE_DIR>/i18n/zh-Hans/plugin-content-docs/foo"`,
+    );
   });
   it('gets correct path when no sub-paths', () => {
     expect(
       getPluginI18nPath({
-        siteDir: __dirname,
-        locale: 'zh-Hans',
+        localizationDir: '<SITE_DIR>/i18n/zh-Hans',
         pluginName: 'plugin-content-docs',
-      }).replace(__dirname, ''),
-    ).toMatchInlineSnapshot(`"/i18n/zh-Hans/plugin-content-docs"`);
+      }),
+    ).toMatchInlineSnapshot(`"<SITE_DIR>/i18n/zh-Hans/plugin-content-docs"`);
   });
 });
 
@@ -104,6 +103,7 @@ describe('localizePath', () => {
         path: '/baseUrl',
         i18n: {
           defaultLocale: 'en',
+          path: 'i18n',
           locales: ['en', 'fr'],
           currentLocale: 'fr',
           localeConfigs: {},
@@ -120,6 +120,7 @@ describe('localizePath', () => {
         path: '/baseFsPath',
         i18n: {
           defaultLocale: 'en',
+          path: 'i18n',
           locales: ['en', 'fr'],
           currentLocale: 'fr',
           localeConfigs: {},
@@ -136,6 +137,7 @@ describe('localizePath', () => {
         path: '/baseUrl/',
         i18n: {
           defaultLocale: 'en',
+          path: 'i18n',
           locales: ['en', 'fr'],
           currentLocale: 'en',
           localeConfigs: {},
@@ -152,6 +154,7 @@ describe('localizePath', () => {
         path: '/baseUrl/',
         i18n: {
           defaultLocale: 'en',
+          path: 'i18n',
           locales: ['en', 'fr'],
           currentLocale: 'en',
           localeConfigs: {},
@@ -167,6 +170,7 @@ describe('localizePath', () => {
         path: '/baseUrl/',
         i18n: {
           defaultLocale: 'en',
+          path: 'i18n',
           locales: ['en', 'fr'],
           currentLocale: 'en',
           localeConfigs: {},

packages/docusaurus-utils/src/constants.ts

@@ -75,7 +75,7 @@ export const THEME_PATH = `${SRC_DIR_NAME}/theme`;
  * All translation-related data live here, relative to site directory. Content
  * will be namespaced by locale.
  */
-export const I18N_DIR_NAME = 'i18n';
+export const DEFAULT_I18N_DIR_NAME = 'i18n';
 
 /**
  * Translations for React code.