feat: add support for internazionalization

Fix #64

.env.example

@@ -1 +1,3 @@
-GITHUB_TOKEN=
+GITHUB_TOKEN=
+CROWDIN_TOKEN=
+CROWDIN_PROJECT_ID=

.gitignore

@@ -3,7 +3,13 @@ node_modules
 .DS_Store
 .env
 .vscode/settings.json
+#####
+blog/
 build/
 content/
 docs/
-blog/
+# Temp folders used during pre-build
+temp-docs/
+temp-i18n/
+i18n/
+!i18n/en-US/

.vscode/launch.json

@@ -4,6 +4,14 @@
   // For more information, visit: https://go.microsoft.com/fwlink/?linkid=830387
   "version": "0.2.0",
   "configurations": [
+    {
+      "name": "Current file",
+      "program": "${file}",
+      "request": "launch",
+      "cwd": "${workspaceFolder}",
+      "skipFiles": ["<node_internals>/**"],
+      "type": "pwa-node"
+    },
     {
       "type": "node",
       "name": "vscode-jest-tests",

docusaurus.config.js

@@ -12,6 +12,10 @@ module.exports = {
   favicon: 'img/favicon.ico',
   organizationName: 'electron',
   projectName: 'electron',
+  i18n: {
+    defaultLocale: 'en',
+    locales: ['en', 'es-ES']
+  },
   themeConfig: {
     announcementBar: {
       id: 'to_old_docs',
@@ -45,6 +49,10 @@ module.exports = {
           position: 'left',
           activeBaseRegex: '^\b$' // never active
         },
+        {
+          type: 'localeDropdown',
+          position: 'right',
+        },
         {
           href: 'https://github.com/electron/electron',
           label: 'GitHub',
@@ -99,7 +107,7 @@ module.exports = {
           ],
         },
       ],
-      copyright: `Copyright © ${new Date().getFullYear()} My Project, Inc. Built with Docusaurus.`,
+      copyright: `Copyright © OpenJS Foundation and Electron contributors.`,
     },
     algolia: {
       apiKey: 'f9fb1d51a99fc479d5979cfa2aae48b9',

i18n/en-US/docusaurus-theme-classic/footer.json

@@ -40,7 +40,7 @@
     "description": "The label of footer link with label=GitHub linking to https://github.com/electron/electron"
   },
   "copyright": {
-    "message": "Copyright © 2021 My Project, Inc. Built with Docusaurus.",
+    "message": "Copyright © OpenJS Foundation and Electron contributors.",
     "description": "The footer copyright"
   }
 }

package.json

@@ -48,6 +48,7 @@
   "devDependencies": {
     "@actions/core": "^1.2.7",
     "@actions/github": "^4.0.0",
+    "@crowdin/crowdin-api-client": "^1.11.1",
     "@types/jest": "^26.0.23",
     "@types/unist": "^2.0.3",
     "del": "^6.0.0",
@@ -62,7 +63,8 @@
     "make-dir": "^3.1.0",
     "prettier": "^2.2.1",
     "tar-stream": "^2.2.0",
-    "unist-util-visit-parents": "^3.1.1"
+    "unist-util-visit-parents": "^3.1.1",
+    "unzipper": "^0.10.11"
   },
   "sha": "0cd80cd424495b9efd244ae7d57f980ad43780ff"
 }

scripts/pre-build.js

@@ -7,34 +7,102 @@
  */
 const path = require('path');
 const { existsSync } = require('fs');
+const fs = require('fs-extra');
 
-const del = require('del');
 const latestVersion = require('latest-version');
 
-const { copy, download } = require('./tasks/download-docs');
+const { cleanProject } = require('./tasks/clean-project');
+const { download } = require('./tasks/download-docs');
+const { copy, copyStaticAssets } = require('./tasks/reorg-docs');
 const { addFrontmatter } = require('./tasks/add-frontmatter');
 const { createSidebar } = require('./tasks/create-sidebar');
 const { fixContent } = require('./tasks/md-fixers');
 const { copyNewContent } = require('./tasks/copy-new-content');
+const { downloadTranslations } = require('./tasks/download-translations');
+
 const { sha } = require('../package.json');
 
 const DOCS_FOLDER = 'docs';
+const DOCS_TEMP_FOLDER = 'temp-docs';
+const TEMP_I18N_FOLDER = 'temp-i18n';
+const I18N_FOLDER = 'i18n';
+
+const CROWDIN_CONTENT_PATH = path.join(
+  TEMP_I18N_FOLDER,
+  '[electron.i18n] master/content'
+);
 // const BLOG_FOLDER = 'blog';
 
+/**
+ * Performs all the required transformations and fixes for the given path.
+ * @param {string} localeTarget The root where or the markdown docs are. For the
+ * original content it should be `docs/`, and
+ * `i18n/%locale%/docusaurus-plugin-content-docs/current/` for the localized one.
+ */
+const processLocale = async (localeTarget) => {
+  console.log('Copying new content');
+  await copyNewContent(localeTarget);
+
+  console.log('Fixing markdown');
+  await fixContent(localeTarget);
+
+  console.log('Adding automatic frontmatter');
+  await addFrontmatter(localeTarget);
+};
+
+/**
+ * Updates the navbar for the original content and the localized one.
+ * @param {string} localeTarget
+ */
+const processNavigations = async (localeTarget) => {
+  console.log('Updating sidebar.js');
+  if (!localeTarget.includes(I18N_FOLDER)) {
+    await createSidebar(localeTarget, path.join(process.cwd(), 'sidebars.js'));
+  }
+};
+
+/**
+ * Downloads the translations from Crowdin and makes sure all the files
+ * are in the right place or generated if needed.
+ */
+const processLocales = async () => {
+  console.log('Downloading latest translations');
+  await downloadTranslations(TEMP_I18N_FOLDER);
+
+  // The contents are the locales folders names, i.e.: `de-DE`, `es-ES`, etc.
+  const locales = await fs.readdir(CROWDIN_CONTENT_PATH);
+
+  for (const locale of locales) {
+    const source = path.join(CROWDIN_CONTENT_PATH, locale);
+    const localeTarget = path.join('i18n', locale);
+    const docsTarget = path.join(
+      localeTarget,
+      'docusaurus-plugin-content-docs',
+      'current'
+    );
+    console.log(`Copying contents from "${source}" to "${docsTarget}"`);
+    await copy(source, docsTarget, 'docs');
+    await copyStaticAssets(DOCS_FOLDER, docsTarget);
+    // The non-markdown content is under the `website/i18n` folder in crowdin
+    // It keeps the right structure so it just needs to be copy over to the locale folder
+    await fs.copy(path.join(source, 'website', 'i18n'), localeTarget);
+
+    await processLocale(docsTarget);
+    await processNavigations(localeTarget);
+  }
+};
+
 /**
  *
  * @param {string} source
  */
 const start = async (source) => {
-  console.log(`Deleting previous content`);
-  await del(DOCS_FOLDER);
+  console.log(`Cleaning project`);
+  await cleanProject(path.join(process.cwd(), '.gitignore'));
 
   const localElectron =
     source && (source.includes('/') || source.includes('\\'));
 
-  // TODO: Uncomment once we have the blog up and running
-  // await del(BLOG_FOLDER);
-
   if (!localElectron) {
     console.log(`Detecting latest Electron version`);
     const version = await latestVersion('electron');
@@ -50,19 +118,29 @@ const start = async (source) => {
       target,
       org: process.env.ORG || 'electron',
       repository: 'electron',
-      destination: DOCS_FOLDER,
       downloadMatch: 'docs',
+      destination: DOCS_TEMP_FOLDER,
     });
+    await copy(DOCS_TEMP_FOLDER, DOCS_FOLDER);
   } else if (existsSync(source)) {
-    await copy({
-      target: source,
-      destination: DOCS_FOLDER,
-      downloadMatch: 'docs',
-    });
+    await copy(source, DOCS_FOLDER, 'docs');
   } else {
     console.error(`Path ${localElectron} does not exist`);
     return process.exit(-1);
   }
+  await processLocale(DOCS_FOLDER);
+  await processNavigations(DOCS_FOLDER);
+
+  // No need to download translations if the source content is local
+  if (localElectron) {
+    return;
+  }
+
+  if(process.env.CROWDIN_TOKEN && process.env.CROWDIN_PROJECT_ID) {
+    await processLocales();
+  }else{
+    console.log(`CROWDIN_TOKEN and/or CROWDIN_PROJECT_ID are missing. Skipping downloading translations.`);
+  }
 
   // TODO: Uncoment once we have the blog enabled
   // console.log(`Downloading posts`);
@@ -72,18 +150,6 @@ const start = async (source) => {
   //   destination: BLOG_FOLDER,
   //   downloadMatch: 'data/blog',
   // });
-
-  console.log('Copying new content');
-  await copyNewContent(DOCS_FOLDER);
-
-  console.log('Fixing markdown');
-  await fixContent(DOCS_FOLDER);
-
-  console.log('Adding automatic frontmatter');
-  await addFrontmatter(DOCS_FOLDER);
-
-  console.log('Updating sidebar.js');
-  await createSidebar(DOCS_FOLDER, path.join(process.cwd(), 'sidebars.js'));
 };
 
 start(process.argv[2]);

scripts/tasks/clean-project.js

@@ -0,0 +1,44 @@
+//@ts-check
+const fs = require('fs').promises;
+const { join } = require('path');
+const del = require('del');
+
+const splitPattern = `#####`;
+
+/**
+ * Gets the patterns to use from `contents`:
+ * * Contents after the `splitPattern`
+ * * No comment lines
+ * * No empty lines
+ *
+ * @param {string} contents
+ */
+const getPatterns = (contents) => {
+  const [, toDelete] = contents.split(splitPattern);
+
+  return toDelete
+    .trim()
+    .split('\n')
+    .filter((line) => !line.startsWith('#'))
+    .map((line) => line.trim());
+};
+
+/**
+ * Deletes all the patterns specified in the provided .gitignore
+ * after the pattern `#####`
+ * @param {string} gitignorePath
+ */
+const cleanProject = async (gitignorePath) => {
+  const gitignore = await fs.readFile(gitignorePath, 'utf-8');
+  const toDelete = getPatterns(gitignore);
+
+  const files = await del(toDelete, { dryRun: true });
+};
+
+if (require.main === module) {
+  cleanProject(join(process.cwd(), '.gitignore'));
+}
+
+module.exports = {
+  cleanProject,
+};