feat(v2): core v2 i18n support + Docusaurus site Crowdin integration

.gitignore

@@ -31,8 +31,12 @@ packages/docusaurus-theme-classic/lib/
 packages/docusaurus-theme-bootstrap/lib/
 packages/docusaurus-migrate/lib/
 
-website/netlifyDeployPreview
+website/netlifyDeployPreview/*
 !website/netlifyDeployPreview/index.html
 !website/netlifyDeployPreview/_redirects
 
 website-1.x-migrated
+
+website/i18n/**/*
+!website/i18n/*
+!website/i18n/*/translations.json

crowdin-v2.yaml

@@ -0,0 +1,134 @@
+#
+# Your Crowdin credentials
+#
+'project_id': '416738'
+'api_token_env': 'CROWDIN_PERSONAL_TOKEN'
+'base_path': '.'
+'base_url': 'https://api.crowdin.com'
+
+#
+# Choose file structure in Crowdin
+# e.g. true or false
+#
+'preserve_hierarchy': true
+
+#
+# Files configuration
+#
+files:
+  [
+    {
+      'source': '/website/docs/**/*',
+      'translation': '/website/i18n/%two_letters_code%/docs/current/**/%original_file_name%',
+    },
+    {
+      'source': '/website/versioned_docs/**/*',
+      'translation': '/website/i18n/%two_letters_code%/docs/**/%original_file_name%',
+    },
+    {
+      'source': '/website-1.x/blog/**/*',
+      'translation': '/website/i18n/%two_letters_code%/blog/**/%original_file_name%',
+    },
+    {
+      'source': '/website/src/pages/**/*',
+      'translation': '/website/i18n/%two_letters_code%/pages/**/%original_file_name%',
+      'ignore': ['/**/*.js', '/**/*.jsx', '/**/*.ts', '/**/*.tsx', '/**/*.css'],
+    },
+  ]
+#
+# Source files filter
+# e.g. "/resources/en/*.json"
+#
+#"source" : "/website/docs/**/*.md",
+#
+# Where translations will be placed
+# e.g. "/resources/docs/%two_letters_code%/%original_file_name%"
+#
+#"translation" : "/website/i18n/%language%/docs/current/%original_file_name%",
+#
+# Files or directories for ignore
+# e.g. ["/**/?.txt", "/**/[0-9].txt", "/**/*\?*.txt"]
+#
+#"ignore" : [],
+#
+# The dest allows you to specify a file name in Crowdin
+# e.g. "/messages.json"
+#
+#"dest" : "",
+#
+# File type
+# e.g. "json"
+#
+#"type" : "",
+#
+# The parameter "update_option" is optional. If it is not set, after the files update the translations for changed strings will be removed. Use to fix typos and for minor changes in the source strings
+# e.g. "update_as_unapproved" or "update_without_changes"
+#
+#"update_option" : "",
+#
+# Start block (for XML only)
+#
+#
+# Defines whether to translate tags attributes.
+# e.g. 0 or 1  (Default is 1)
+#
+# "translate_attributes" : 1,
+#
+# Defines whether to translate texts placed inside the tags.
+# e.g. 0 or 1 (Default is 1)
+#
+# "translate_content" : 1,
+#
+# This is an array of strings, where each item is the XPaths to DOM element that should be imported
+# e.g. ["/content/text", "/content/text[@value]"]
+#
+# "translatable_elements" : [],
+#
+# Defines whether to split long texts into smaller text segments
+# e.g. 0 or 1 (Default is 1)
+#
+# "content_segmentation" : 1,
+#
+# End block (for XML only)
+#
+#
+# Start .properties block
+#
+#
+# Defines whether single quote should be escaped by another single quote or backslash in exported translations
+# e.g. 0 or 1 or 2 or 3 (Default is 3)
+# 0 - do not escape single quote;
+# 1 - escape single quote by another single quote;
+# 2 - escape single quote by backslash;
+# 3 - escape single quote by another single quote only in strings containing variables ( {0} ).
+#
+# "escape_quotes" : 3,
+#
+# Defines whether any special characters (=, :, ! and #) should be escaped by backslash in exported translations.
+# e.g. 0 or 1 (Default is 0)
+# 0 - do not escape special characters
+# 1 - escape special characters by a backslash
+#
+# "escape_special_characters": 0
+#
+#
+# End .properties block
+#
+#
+# Often software projects have custom names for the directories where translations are placed. crowdin-cli allows you to map your own languages to be understandable by Crowdin.
+#
+#"languages_mapping" : {
+#  "two_letters_code" : {
+#    "crowdin_language_code" : "local_name"
+#   }
+#},
+#
+# Does the first line contain header?
+# e.g. true or false
+#
+#"first_line_contains_header" : true,
+#
+# for spreadsheets
+# e.g. "identifier,source_phrase,context,uk,ru,fr"
+#
+# "scheme" : "",

package.json

@@ -29,7 +29,8 @@
     "serve:v2:ssl:message": "echo '\n\n\nServing Docusaurus with HTTPS on localhost requires to disable the Chrome security: chrome://flags/#allow-insecure-localhost\n\n\n'",
     "serve:v2:ssl:serve": "serve website/build --ssl-cert ./website/.docusaurus/selfsigned.crt --ssl-key ./website/.docusaurus/selfsigned.key",
     "changelog": "lerna-changelog",
-    "postinstall": "yarn build:packages",
+    "postinstall": "test -n \"$NO_YARN_POST_INSTALL\" || yarn build:packages",
+    "install:fast": "NO_YARN_POST_INSTALL=true yarn install",
     "prettier": "prettier --config .prettierrc --write \"**/*.{js,ts}\"",
     "prettier:diff": "prettier --config .prettierrc --list-different \"**/*.{js,ts}\"",
     "prettier-docs": "prettier --config .prettierrc --write \"**/*.md\"",

packages/docusaurus-module-type-aliases/src/index.d.ts

@@ -47,6 +47,17 @@ declare module '@generated/globalData' {
   export default globalData;
 }
 
+declare module '@generated/i18n' {
+  const i18n: {
+    context: any; // TODO
+    translations: {
+      plugins: any; // TODO
+      code: Record<string, string>;
+    };
+  };
+  export default i18n;
+}
+
 declare module '@theme/*';
 
 declare module '@theme-original/*';
@@ -69,6 +80,14 @@ declare module '@docusaurus/Link' {
   export default Link;
 }
 
+declare module '@docusaurus/Translate' {
+  type TranslateProps = {children: string};
+  const Translate: (props: TranslateProps) => JSX.Element;
+  export default Translate;
+
+  export function translate(text: string): string;
+}
+
 declare module '@docusaurus/router' {
   export const Redirect: (props: {to: string}) => import('react').Component;
   export function matchPath(

packages/docusaurus-plugin-client-redirects/src/index.ts

@@ -14,7 +14,7 @@ import writeRedirectFiles, {
   toRedirectFilesMetadata,
   RedirectFileMetadata,
 } from './writeRedirectFiles';
-import {removePrefix} from '@docusaurus/utils';
+import {removePrefix, addLeadingSlash} from '@docusaurus/utils';
 
 export default function pluginClientRedirectsPages(
   _context: LoadContext,
@@ -27,7 +27,7 @@ export default function pluginClientRedirectsPages(
     async postBuild(props: Props) {
       const pluginContext: PluginContext = {
         relativeRoutesPaths: props.routesPaths.map(
-          (path) => `/${removePrefix(path, props.baseUrl)}`,
+          (path) => `${addLeadingSlash(removePrefix(path, props.baseUrl))}`,
         ),
         baseUrl: props.baseUrl,
         outDir: props.outDir,

packages/docusaurus-plugin-content-blog/package.json

@@ -28,6 +28,7 @@
     "feed": "^4.1.0",
     "fs-extra": "^8.1.0",
     "globby": "^10.0.1",
+    "lodash": "^4.17.19",
     "loader-utils": "^1.2.3",
     "lodash": "^4.5.2",
     "reading-time": "^1.2.0",

packages/docusaurus-plugin-content-blog/src/__tests__/__fixtures__/website/blog-with-ref/post-with-broken-links.md

@@ -0,0 +1,11 @@
+---
+title: This post links to another one!
+---
+
+[Good link 1](2018-12-14-Happy-First-Birthday-Slash.md)
+
+[Good link 2](./2018-12-14-Happy-First-Birthday-Slash.md)
+
+[Bad link 1](postNotExist1.md)
+
+[Bad link 1](./postNotExist2.mdx)

packages/docusaurus-plugin-content-blog/src/__tests__/__snapshots__/linkify.test.ts.snap

@@ -1,5 +1,20 @@
 // Jest Snapshot v1, https://goo.gl/fbAQLP
 
+exports[`report broken markdown links 1`] = `
+"---
+title: This post links to another one!
+---
+
+[Good link 1](/blog/2018/12/14/Happy-First-Birthday-Slash)
+
+[Good link 2](/blog/2018/12/14/Happy-First-Birthday-Slash)
+
+[Bad link 1](postNotExist1.md)
+
+[Bad link 1](./postNotExist2.mdx)
+"
+`;
+
 exports[`transform to correct link 1`] = `
 "---
 title: This post links to another one!

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

@@ -7,11 +7,14 @@
 
 import fs from 'fs-extra';
 import path from 'path';
-import {linkify} from '../blogUtils';
-import {BlogPost} from '../types';
+import {linkify, LinkifyParams} from '../blogUtils';
+import {BlogBrokenMarkdownLink, BlogContentPaths, BlogPost} from '../types';
 
-const sitePath = path.join(__dirname, '__fixtures__', 'website');
-const blogPath = path.join(sitePath, 'blog-with-ref');
+const siteDir = path.join(__dirname, '__fixtures__', 'website');
+const contentPaths: BlogContentPaths = {
+  contentPath: path.join(siteDir, 'blog-with-ref'),
+  contentPathLocalized: path.join(siteDir, 'blog-with-ref-localized'),
+};
 const pluginDir = 'blog-with-ref';
 const blogPosts: BlogPost[] = [
   {
@@ -36,14 +39,26 @@ const blogPosts: BlogPost[] = [
   },
 ];
 
-const transform = (filepath: string) => {
-  const content = fs.readFileSync(filepath, 'utf-8');
-  const transformedContent = linkify(content, sitePath, blogPath, blogPosts);
-  return [content, transformedContent];
+const transform = (filePath: string, options?: Partial<LinkifyParams>) => {
+  const fileContent = fs.readFileSync(filePath, 'utf-8');
+  const transformedContent = linkify({
+    filePath,
+    fileContent,
+    siteDir,
+    contentPaths,
+    blogPosts,
+    onBrokenMarkdownLink: (brokenMarkdownLink) => {
+      throw new Error(
+        `Broken markdown link found: ${JSON.stringify(brokenMarkdownLink)}`,
+      );
+    },
+    ...options,
+  });
+  return [fileContent, transformedContent];
 };
 
 test('transform to correct link', () => {
-  const post = path.join(blogPath, 'post.md');
+  const post = path.join(contentPaths.contentPath, 'post.md');
   const [content, transformedContent] = transform(post);
   expect(transformedContent).toMatchSnapshot();
   expect(transformedContent).toContain(
@@ -54,3 +69,25 @@ test('transform to correct link', () => {
   );
   expect(content).not.toEqual(transformedContent);
 });
+
+test('report broken markdown links', () => {
+  const filePath = 'post-with-broken-links.md';
+  const folderPath = contentPaths.contentPath;
+  const postWithBrokenLinks = path.join(folderPath, filePath);
+  const onBrokenMarkdownLink = jest.fn();
+  const [, transformedContent] = transform(postWithBrokenLinks, {
+    onBrokenMarkdownLink,
+  });
+  expect(transformedContent).toMatchSnapshot();
+  expect(onBrokenMarkdownLink).toHaveBeenCalledTimes(2);
+  expect(onBrokenMarkdownLink).toHaveBeenNthCalledWith(1, {
+    filePath: path.resolve(folderPath, filePath),
+    folderPath,
+    link: 'postNotExist1.md',
+  } as BlogBrokenMarkdownLink);
+  expect(onBrokenMarkdownLink).toHaveBeenNthCalledWith(2, {
+    filePath: path.resolve(folderPath, filePath),
+    folderPath,
+    link: './postNotExist2.mdx',
+  } as BlogBrokenMarkdownLink);
+});