feat(v2): Add Interpolate / interpolate APIs + complete theme translations

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

@@ -84,15 +84,60 @@ declare module '@docusaurus/Link' {
   export default Link;
 }
 
+declare module '@docusaurus/Interpolate' {
+  import type {ReactNode} from 'react';
+
+  // TODO use TS template literal feature to make values typesafe!
+  // (requires upgrading TS first)
+  // eslint-disable-next-line @typescript-eslint/no-unused-vars
+  export type ExtractInterpolatePlaceholders<Str extends string> = string;
+
+  export type InterpolateValues<
+    Str extends string,
+    Value extends ReactNode
+  > = Record<ExtractInterpolatePlaceholders<Str>, Value>;
+
+  // TS function overload: if all the values are plain strings, then interpolate returns a simple string
+  export function interpolate<Str extends string>(
+    text: Str,
+    values?: InterpolateValues<Str, string | number>,
+  ): string;
+
+  // If values contain any ReactNode, then the return is a ReactNode
+  export function interpolate<Str extends string, Value extends ReactNode>(
+    text: Str,
+    values?: InterpolateValues<Str, Value>,
+  ): ReactNode;
+
+  export type InterpolateProps<Str extends string> = {
+    children: Str;
+    values?: InterpolateValues<Str, ReactNode>;
+  };
+
+  export default function Interpolate<Str extends string>(
+    props: InterpolateProps<Str>,
+  ): JSX.Element;
+}
+
 declare module '@docusaurus/Translate' {
-  type TranslateProps = {children: string; id?: string; description?: string};
-  const Translate: (props: TranslateProps) => JSX.Element;
-  export default Translate;
+  import type {
+    InterpolateProps,
+    InterpolateValues,
+  } from '@docusaurus/Interpolate';
+
+  type TranslateProps<Str extends string> = InterpolateProps<Str> & {
+    id?: string;
+    description?: string;
+  };
+  export default function Translate<Str extends string>(
+    props: TranslateProps<Str>,
+  ): JSX.Element;
 
-  export function translate(param: {
-    message: string;
+  export function translate<Str extends string>(param: {
+    message: Str;
     id?: string;
     description?: string;
+    values?: InterpolateValues<Str, string | number>;
   }): string;
 }
 

packages/docusaurus-theme-classic/codeTranslations/base.json

@@ -40,5 +40,29 @@
   "theme.PwaReloadPopup.refreshButtonText": "Refresh",
   "theme.PwaReloadPopup.closeButtonAriaLabel": "Close",
   "theme.Playground.liveEditor": "Live Editor",
-  "theme.Playground.result": "Result"
+  "theme.Playground.result": "Result",
+  "common.month.january": "January",
+  "common.month.february": "February",
+  "common.month.march": "March",
+  "common.month.april": "April",
+  "common.month.may": "May",
+  "common.month.june": "June",
+  "common.month.july": "July",
+  "common.month.august": "August",
+  "common.month.september": "September",
+  "common.month.october": "October",
+  "common.month.november": "November",
+  "common.month.december": "December",
+  "theme.blog.post.date": "{{month}} {{day}}, {{year}}",
+  "theme.blog.post.readingTime": "{{readingTime}} min read",
+  "theme.blog.post.onePost": "One post",
+  "theme.blog.post.nPosts": "{{count}} posts",
+  "theme.blog.tagTitle": "{{nPosts}} tagged with \"{{tagName}}\"",
+  "theme.docs.versions.unreleasedVersionLabel": "This is unreleased documentation for {{siteTitle}} {{versionLabel}} version.",
+  "theme.docs.versions.unmaintainedVersionLabel": "This is documentation for {{siteTitle}} {{versionLabel}}, which is no longer actively maintained.",
+  "theme.docs.versions.latestVersionSuggestionLabel": "For up-to-date documentation, see the {{latestVersionLink}} ({{versionLabel}}).",
+  "theme.docs.versions.latestVersionLinkLabel": "latest version",
+  "theme.lastUpdated.atDate": "on {{date}}",
+  "theme.lastUpdated.byUser": "by {{user}}",
+  "theme.lastUpdated.lastUpdatedAtBy": "Last updated{{atDate}}{{byUser}}"
 }

packages/docusaurus-theme-classic/codeTranslations/fr.json

@@ -40,5 +40,29 @@
   "theme.PwaReloadPopup.refreshButtonText": "Rafraichir",
   "theme.PwaReloadPopup.closeButtonAriaLabel": "Fermer",
   "theme.Playground.liveEditor": "Éditeur en direct",
-  "theme.Playground.result": "Résultat"
+  "theme.Playground.result": "Résultat",
+  "common.month.january": "Janvier",
+  "common.month.february": "Février",
+  "common.month.march": "Mars",
+  "common.month.april": "Avril",
+  "common.month.may": "Mai",
+  "common.month.june": "Juin",
+  "common.month.july": "Juillet",
+  "common.month.august": "Août",
+  "common.month.september": "Septembre",
+  "common.month.october": "Octobre",
+  "common.month.november": "Novembre",
+  "common.month.december": "Décembre",
+  "theme.blog.post.date": "{{day}} {{month}} {{year}}",
+  "theme.blog.post.readingTime": "{{readingTime}} min de lecture",
+  "theme.blog.post.onePost": "Un article",
+  "theme.blog.post.nPosts": "{{count}} articles",
+  "theme.blog.tagTitle": "{{nPosts}} taggés avec \"{{tagName}}\"",
+  "theme.docs.versions.unreleasedVersionLabel": "Ceci est la documentation de la prochaine version {{versionLabel}} de {{siteTitle}}.",
+  "theme.docs.versions.unmaintainedVersionLabel": "Ceci est la documentation de {{siteTitle}} {{versionLabel}}, qui n'est plus activement maintenue.",
+  "theme.docs.versions.latestVersionSuggestionLabel": "Pour une documentation à jour, consultez la {{latestVersionLink}} ({{versionLabel}}).",
+  "theme.docs.versions.latestVersionLinkLabel": "dernière version",
+  "theme.lastUpdated.atDate": "le {{date}}",
+  "theme.lastUpdated.byUser": "par {{user}}",
+  "theme.lastUpdated.lastUpdatedAtBy": "Dernière mise à jour{{atDate}}{{byUser}}"
 }

packages/docusaurus-theme-classic/src/theme/BlogPostItem/index.tsx

@@ -8,7 +8,7 @@
 import React from 'react';
 import clsx from 'clsx';
 import {MDXProvider} from '@mdx-js/react';
-import Translate from '@docusaurus/Translate';
+import Translate, {translate} from '@docusaurus/Translate';
 import Link from '@docusaurus/Link';
 import MDXComponents from '@theme/MDXComponents';
 import Seo from '@theme/Seo';
@@ -17,18 +17,66 @@ import type {Props} from '@theme/BlogPostItem';
 import styles from './styles.module.css';
 
 const MONTHS = [
-  'January',
-  'February',
-  'March',
-  'April',
-  'May',
-  'June',
-  'July',
-  'August',
-  'September',
-  'October',
-  'November',
-  'December',
+  translate({
+    id: 'common.month.january',
+    description: 'January month translation',
+    message: 'January',
+  }),
+  translate({
+    id: 'common.month.february',
+    description: 'February month translation',
+    message: 'February',
+  }),
+  translate({
+    id: 'common.month.march',
+    description: 'March month translation',
+    message: 'March',
+  }),
+  translate({
+    id: 'common.month.april',
+    description: 'April month translation',
+    message: 'April',
+  }),
+  translate({
+    id: 'common.month.may',
+    description: 'May month translation',
+    message: 'May',
+  }),
+  translate({
+    id: 'common.month.june',
+    description: 'June month translation',
+    message: 'June',
+  }),
+  translate({
+    id: 'common.month.july',
+    description: 'July month translation',
+    message: 'July',
+  }),
+  translate({
+    id: 'common.month.august',
+    description: 'August month translation',
+    message: 'August',
+  }),
+  translate({
+    id: 'common.month.september',
+    description: 'September month translation',
+    message: 'September',
+  }),
+  translate({
+    id: 'common.month.october',
+    description: 'October month translation',
+    message: 'October',
+  }),
+  translate({
+    id: 'common.month.november',
+    description: 'November month translation',
+    message: 'November',
+  }),
+  translate({
+    id: 'common.month.december',
+    description: 'December month translation',
+    message: 'December',
+  }),
 ];
 
 function BlogPostItem(props: Props): JSX.Element {
@@ -62,8 +110,25 @@ function BlogPostItem(props: Props): JSX.Element {
         </TitleHeading>
         <div className="margin-vert--md">
           <time dateTime={date} className={styles.blogPostDate}>
-            {month} {day}, {year}{' '}
-            {readingTime && <> · {Math.ceil(readingTime)} min read</>}
+            <Translate
+              id="theme.blog.post.date"
+              description="The label to display the blog post date"
+              values={{day, month, year}}>
+              {'{{month}} {{day}}, {{year}}'}
+            </Translate>{' '}
+            {readingTime && (
+              <>
+                {' · '}
+                <Translate
+                  id="theme.blog.post.readingTime"
+                  description="The label to display reading time of the blog post"
+                  values={{
+                    readingTime: Math.ceil(readingTime),
+                  }}>
+                  {'{{readingTime}} min read'}
+                </Translate>
+              </>
+            )}
           </time>
         </div>
         <div className="avatar margin-vert--md">

packages/docusaurus-theme-classic/src/theme/BlogTagsListPage/index.tsx

@@ -50,7 +50,6 @@ function BlogTagsListPage(props: Props): JSX.Element {
     ))
     .filter((item) => item != null);
 
-  // TODO soon: translate hardcoded labels, but factorize them (blog + docs will both have tags)
   return (
     <Layout
       title="Tags"

packages/docusaurus-theme-classic/src/theme/BlogTagsPostsPage/index.tsx

@@ -12,17 +12,29 @@ import BlogPostItem from '@theme/BlogPostItem';
 import Link from '@docusaurus/Link';
 import type {Props} from '@theme/BlogTagsPostsPage';
 import BlogSidebar from '@theme/BlogSidebar';
-import Translate from '@docusaurus/Translate';
+import Translate, {translate} from '@docusaurus/Translate';
 
-function pluralize(count: number, word: string) {
-  return count > 1 ? `${word}s` : word;
+// Very simple pluralization: probably good enough for now
+function pluralizePosts(count: number): string {
+  return count === 1
+    ? translate({
+        id: 'theme.blog.post.onePost',
+        description: 'Label to describe one blog post',
+        message: 'One post',
+        values: {count},
+      })
+    : translate({
+        id: 'theme.blog.post.nPosts',
+        description: 'Label to describe multiple blog posts',
+        message: '{{count}} posts',
+        values: {count},
+      });
 }
 
 function BlogTagsPostPage(props: Props): JSX.Element {
   const {metadata, items, sidebar} = props;
   const {allTagsPath, name: tagName, count} = metadata;
 
-  // TODO soon: translate hardcoded labels, but factorize them (blog + docs will both have tags)
   return (
     <Layout
       title={`Posts tagged "${tagName}"`}
@@ -35,8 +47,12 @@ function BlogTagsPostPage(props: Props): JSX.Element {
           </div>
           <main className="col col--8">
             <h1>
-              {count} {pluralize(count, 'post')} tagged with &quot;{tagName}
-              &quot;
+              <Translate
+                id="theme.blog.tagTitle"
+                description="The title of the page for a blog tag"
+                values={{nPosts: pluralizePosts(count), tagName}}>
+                {'{{nPosts}} tagged with "{{tagName}}"'}
+              </Translate>
             </h1>
             <Link href={allTagsPath}>
               <Translate

packages/docusaurus-theme-classic/src/theme/DocItem/index.tsx

@@ -9,6 +9,7 @@ import React from 'react';
 import DocPaginator from '@theme/DocPaginator';
 import DocVersionSuggestions from '@theme/DocVersionSuggestions';
 import Seo from '@theme/Seo';
+import LastUpdated from '@theme/LastUpdated';
 import type {Props} from '@theme/DocItem';
 import TOC from '@theme/TOC';
 import EditThisPage from '@theme/EditThisPage';
@@ -78,42 +79,10 @@ function DocItem(props: Props): JSX.Element {
                     {editUrl && <EditThisPage editUrl={editUrl} />}
                   </div>
                   {(lastUpdatedAt || lastUpdatedBy) && (
-                    <div className="col text--right">
-                      <em>
-                        <small>
-                          {/* TODO: wait for using interpolation in translation function */}
-                          Last updated{' '}
-                          {lastUpdatedAt && (
-                            <>
-                              on{' '}
-                              <time
-                                dateTime={new Date(
-                                  lastUpdatedAt * 1000,
-                                ).toISOString()}
-                                className={styles.docLastUpdatedAt}>
-                                {new Date(
-                                  lastUpdatedAt * 1000,
-                                ).toLocaleDateString()}
-                              </time>
-                              {lastUpdatedBy && ' '}
-                            </>
-                          )}
-                          {lastUpdatedBy && (
-                            <>
-                              by <strong>{lastUpdatedBy}</strong>
-                            </>
-                          )}
-                          {process.env.NODE_ENV === 'development' && (
-                            <div>
-                              <small>
-                                {' '}
-                                (Simulated during dev for better perf)
-                              </small>
-                            </div>
-                          )}
-                        </small>
-                      </em>
-                    </div>
+                    <LastUpdated
+                      lastUpdatedAt={lastUpdatedAt}
+                      lastUpdatedBy={lastUpdatedBy}
+                    />
                   )}
                 </div>
               </div>

packages/docusaurus-theme-classic/src/theme/DocItem/styles.module.css

@@ -26,7 +26,3 @@
     padding: 0 0.3rem;
   }
 }
-
-.docLastUpdatedAt {
-  font-weight: bold;
-}