@lexibase/rdx-next 5.2.0 → 6.0.1

package/bin/cli.mjs

@@ -26,7 +26,7 @@ export async function runRdxCli({ templateDir } = {}) {
     templateDir ?? path.join(packageRoot, 'templates', 'runtime')
   const runtimeDirectory = path.join(projectRoot, '.rdx')
 
-  async function prepareRuntime(project) {
+  async function prepareRuntime(project, homepageTranslations) {
     await mkdir(runtimeDirectory, { recursive: true })
     await preparePublicAssets(projectRoot, runtimeDirectory)
     await cp(runtimeTemplate, runtimeDirectory, {
@@ -35,6 +35,11 @@ export async function runRdxCli({ templateDir } = {}) {
     })
     await prepareProjectStyles(projectRoot, runtimeDirectory)
     await prepareLocaleRoutes(project, runtimeDirectory, runtimeTemplate)
+    if (homepageTranslations) {
+      const { prepareHomepageTranslations } =
+        await import('./homepage-translations.mjs')
+      await prepareHomepageTranslations(runtimeDirectory, homepageTranslations)
+    }
     // Resolve in Node before Next processes this file: UI may be transitive,
     // and native Tailwind plugins must stay outside the Turbopack module graph.
     const resolvePlugin = createRequire(import.meta.url)
@@ -140,6 +145,20 @@ export async function runRdxCli({ templateDir } = {}) {
       rootDir: projectRoot,
       command,
     })
+    let homepageTranslations
+    if (
+      project.config.homepage?.enabled &&
+      project.config.homepage.translations &&
+      (supportedCommands.has(command) ||
+        command === 'check' ||
+        command === 'prepare')
+    ) {
+      const { readHomepageTranslations } =
+        await import('./homepage-translations.mjs')
+      homepageTranslations = await readHomepageTranslations(project, {
+        report: command === 'check' || command === 'build',
+      })
+    }
     if (command === 'check' || command === 'build') {
       const { checkDocumentation, formatDocumentationCheck } =
         await import('@lexibase/rdx-core/check')
@@ -153,7 +172,7 @@ export async function runRdxCli({ templateDir } = {}) {
       if (command === 'check') return
     }
     if (command === 'prepare') {
-      await prepareRuntime(project)
+      await prepareRuntime(project, homepageTranslations)
       console.log('RDX runtime prepared in .rdx/')
       return
     }
@@ -174,7 +193,7 @@ export async function runRdxCli({ templateDir } = {}) {
       return
     }
 
-    await prepareRuntime(project)
+    await prepareRuntime(project, homepageTranslations)
     const projectRequire = createRequire(path.join(projectRoot, 'package.json'))
     const nextCli = projectRequire.resolve('next/dist/bin/next')
     const child = spawn(

package/bin/homepage-translations.mjs

@@ -0,0 +1,197 @@
+import { readFile, writeFile } from 'node:fs/promises'
+import path from 'node:path'
+
+const sourceFile = 'components/home.tsx'
+const metadataKey = '$metadata'
+
+function missingFile(error) {
+  return error.code === 'ENOENT' || error.code === 'ENOTDIR'
+}
+
+async function readOptional(file) {
+  try {
+    return await readFile(file, 'utf8')
+  } catch (error) {
+    if (!missingFile(error)) throw error
+  }
+}
+
+async function sourcePhrases(rootDir) {
+  const source = await readOptional(path.join(rootDir, sourceFile))
+  if (source === undefined)
+    throw new Error(`Create ${sourceFile} to use homepage.translations.`)
+  const { default: ts } = await import('typescript')
+  const file = ts.createSourceFile(
+    sourceFile,
+    source,
+    ts.ScriptTarget.Latest,
+    true
+  )
+  for (const statement of file.statements) {
+    if (
+      !ts.isExpressionStatement(statement) ||
+      !ts.isStringLiteral(statement.expression)
+    )
+      break
+    if (statement.expression.text === 'use client')
+      throw new Error(
+        `${sourceFile} must be a Server Component when homepage.translations is enabled. Move 'use client' into interactive child components.`
+      )
+  }
+  const phrases = new Set()
+  const warnings = []
+  const passedOn =
+    't is passed on or renamed; phrases translated elsewhere are left out of the translation report'
+  const needsLiteral =
+    't() needs a literal phrase; this call is left out of the translation report'
+  function warn(node, message) {
+    const { line } = file.getLineAndCharacterOfPosition(node.getStart(file))
+    warnings.push({ line: line + 1, message })
+  }
+
+  // Bind identifiers within this file so an unrelated or shadowed t is ignored.
+  const options = { noLib: true, noResolve: true, types: [] }
+  const program = ts.createProgram([sourceFile], options, {
+    ...ts.createCompilerHost(options),
+    getSourceFile: (name) => (name === sourceFile ? file : undefined),
+  })
+  const checker = program.getTypeChecker()
+  const bindings = new Set()
+  function findBindings(node) {
+    if (
+      ts.isBindingElement(node) &&
+      ts.isObjectBindingPattern(node.parent) &&
+      ts.isIdentifier(node.name)
+    ) {
+      const key = node.propertyName ?? node.name
+      if (ts.isStringLiteralLike(key) || ts.isIdentifier(key)) {
+        if (key.text === 't') {
+          if (node.name.text === 't')
+            bindings.add(checker.getSymbolAtLocation(node.name))
+          else warn(node, passedOn)
+        }
+      }
+    }
+    ts.forEachChild(node, findBindings)
+  }
+  findBindings(file)
+
+  function visit(node) {
+    if (ts.isIdentifier(node) && node.text === 't') {
+      const parent = node.parent
+      const symbol = ts.isShorthandPropertyAssignment(parent)
+        ? checker.getShorthandAssignmentValueSymbol(parent)
+        : checker.getSymbolAtLocation(node)
+      if (
+        symbol &&
+        bindings.has(symbol) &&
+        !ts.isBindingElement(parent) &&
+        !ts.isTypeQueryNode(parent)
+      ) {
+        if (ts.isCallExpression(parent) && parent.expression === node) {
+          const [argument] = parent.arguments
+          if (parent.arguments.length === 1 && ts.isStringLiteralLike(argument))
+            phrases.add(argument.text)
+          else warn(node, needsLiteral)
+        } else warn(node, passedOn)
+      }
+    }
+    ts.forEachChild(node, visit)
+  }
+  visit(file)
+  return { phrases, warnings }
+}
+
+export async function readHomepageTranslations(
+  project,
+  { report = false } = {}
+) {
+  const { rootDir, localization } = project
+  const { phrases, warnings } = await sourcePhrases(rootDir)
+  if (report) {
+    for (const { line, message } of warnings.sort((a, b) => a.line - b.line))
+      console.warn(`[RDX] ${sourceFile}:${line}: ${message}`)
+  }
+  phrases.delete(metadataKey)
+  const catalogs = []
+  for (const locale of localization?.locales ?? []) {
+    if (!locale.folder) continue
+    const file = `locale/${locale.folder}/home.json`
+    const raw = await readOptional(path.join(rootDir, file))
+    let messages = {}
+    if (raw !== undefined) {
+      try {
+        const parsed = JSON.parse(raw)
+        if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed))
+          throw new Error('Expected a JSON object.')
+        messages = parsed
+        catalogs.push({ file, locale: locale.path })
+      } catch {
+        console.warn(
+          `[RDX] ${file}: expected a JSON object of homepage phrases. Using the primary text.`
+        )
+      }
+    }
+    if (!report) continue
+    for (const phrase of phrases) {
+      if (
+        !Object.hasOwn(messages, phrase) ||
+        typeof messages[phrase] !== 'string' ||
+        !messages[phrase].trim()
+      )
+        console.warn(
+          `[RDX] ${file}: missing translation for ${JSON.stringify(phrase)}`
+        )
+    }
+    // An unrecognized call may use any of the remaining keys.
+    if (!warnings.length) {
+      for (const phrase of Object.keys(messages)) {
+        if (phrase !== metadataKey && !phrases.has(phrase))
+          console.warn(
+            `[RDX] ${file}: orphaned translation for ${JSON.stringify(phrase)}`
+          )
+      }
+    }
+  }
+  return { catalogs, phrases }
+}
+
+export async function prepareHomepageTranslations(
+  runtime,
+  { catalogs, phrases }
+) {
+  const imports = catalogs.map(
+    ({ file }, index) =>
+      `import messages${index} from ${JSON.stringify(`../${file}`)}`
+  )
+  const entries = catalogs.map(
+    ({ locale }, index) => `  [${JSON.stringify(locale)}, messages${index}],`
+  )
+  await writeFile(
+    path.join(runtime, 'rdx-home.ts'),
+    `import translatedComponent from '../components/home'
+${imports.join('\n')}
+
+const catalogs = new Map<string, Record<string, unknown>>([
+${entries.join('\n')}
+])
+
+const phrases: string[] = ${JSON.stringify([...phrases])}
+
+export function getHomepageTranslation(locale?: string) {
+  return { translatedComponent, messages: locale ? catalogs.get(locale) : undefined }
+}
+
+export function getHomepageSeo(locale?: string) {
+  const translatedLocales = new Set<string>()
+  for (const [path, catalog] of catalogs) {
+    if (phrases.some((phrase) => {
+      const text = Object.hasOwn(catalog, phrase) ? catalog[phrase] : undefined
+      return typeof text === 'string' && text.trim() && text.trim() !== phrase.trim()
+    })) translatedLocales.add(path)
+  }
+  return { translatedLocales, metadata: locale ? catalogs.get(locale)?.${metadataKey} : undefined }
+}
+`
+  )
+}

package/bin/locale-routes.mjs

@@ -84,7 +84,7 @@ export async function prepareLocaleRoutes(project, runtime, template) {
     await emit(
       `app/(rdx-default)/${file}`,
       text
-        .replace(/from '(\.\.\/[^']*rdx-project)'/g, "from '../$1'")
+        .replace(/from '(\.\.\/[^']*rdx-(?:home|project))'/g, "from '../$1'")
         .replace("'./globals.css'", "'../globals.css'")
     )
   }
@@ -110,49 +110,16 @@ export default async function Layout({ children, params }: { children: React.Rea
 }
 `
   )
-  const homeRoute = 'app/(rdx-locales)/[locale]/page.tsx'
-  const localizedHomes = []
-  if (project.config.homepage?.enabled) {
-    for (const locale of project.localization.locales) {
-      if (!locale.folder || locale.code === project.localization.defaultLocale)
-        continue
-
-      const file = path.join(
-        project.rootDir,
-        'locale',
-        locale.folder,
-        'home.tsx'
-      )
-      const exists = await stat(file).then(
-        (entry) => entry.isFile(),
-        (error) => {
-          if (error.code === 'ENOENT' || error.code === 'ENOTDIR') return false
-          throw error
-        }
-      )
-      if (!exists) continue
-
-      // Literal imports let Next compile and trace project-owned components.
-      const specifier = path
-        .relative(path.dirname(path.join(runtime, homeRoute)), file)
-        .split(path.sep)
-        .join('/')
-        .slice(0, -'.tsx'.length)
-      localizedHomes.push(
-        `    case ${JSON.stringify(locale.path)}: return (await import(${JSON.stringify(specifier)})).default`
-      )
-    }
-  }
   await emit(
-    homeRoute,
-    `import { HomePage, getLocalizedProject } from '${provider}'
+    'app/(rdx-locales)/[locale]/page.tsx',
+    `import { HomePage, getHomepageMetadata, getLocalizedProject } from '${provider}'
 import { notFound, permanentRedirect } from 'next/navigation'
+import { getHomepageSeo, getHomepageTranslation } from '../../../rdx-home'
 import { getProject } from '../../../rdx-project'
-async function getLocalizedHome(locale: string) {
-  switch (locale) {
-${localizedHomes.join('\n')}
-    default: return undefined
-  }
+export async function generateMetadata({ params }: { params: Promise<{ locale: string }> }) {
+  const project = await getProject()
+  const { locale } = await params
+  return getHomepageMetadata({ project, locale, ...getHomepageSeo(locale) })
 }
 export default async function Page({ params }: { params: Promise<{ locale: string }> }) {
   const project = await getProject()
@@ -160,8 +127,7 @@ export default async function Page({ params }: { params: Promise<{ locale: strin
   const selected = project.localization?.locales.find(entry => entry.path === locale)
   if (!project.config.homepage?.enabled || !selected) notFound()
   if (selected.code === project.localization!.defaultLocale) permanentRedirect('/')
-  const component = await getLocalizedHome(locale)
-  return <HomePage project={getLocalizedProject(project, locale)} component={component} />
+  return <HomePage project={getLocalizedProject(project, locale)} {...getHomepageTranslation(locale)} />
 }
 `
   )

package/dist/index.d.ts

@@ -1,2 +1,2 @@
 export { defineConfig } from '@lexibase/rdx-core/config';
-export { RDXConfig, RdxHomepage, RdxHomepageProps, RdxMetadata, RdxPlugin, RdxPluginContext, RdxRuntimeConfig } from '@lexibase/rdx-types';
+export { RDXConfig, RdxHomepage, RdxHomepageProps, RdxMetadata, RdxPlugin, RdxPluginContext, RdxRuntimeConfig, RdxTranslatedHomepageProps } from '@lexibase/rdx-types';

package/dist/runtime/index.d.ts

@@ -1,6 +1,6 @@
 import * as react from 'react';
-import { ReactNode } from 'react';
-import { RdxProject, RDXConfig, RdxContentSource, RdxDocPage } from '@lexibase/rdx-types';
+import { ComponentType, ReactNode } from 'react';
+import { RdxProject, RDXConfig, RdxContentSource, RdxDocPage, RdxTranslatedHomepageProps } from '@lexibase/rdx-types';
 export { createRdxProject, getLocalizedProject, getProjectDocsPaths } from '@lexibase/rdx-core';
 import { MetadataRoute, Metadata } from 'next';
 
@@ -32,6 +32,12 @@ declare function getMarkdownResponse(project: RdxProject, path: string[]): Respo
 declare function markdownNotFound(): Response;
 declare function getDocumentMarkdownResponse(project: RdxProject, source: RdxContentSource | undefined, slug: string, documentPath?: DocumentPath): Response;
 
+declare function getHomepageMetadata({ project, locale, translatedLocales, metadata, }: {
+    project: RdxProject;
+    locale?: string;
+    translatedLocales?: ReadonlySet<string>;
+    metadata?: unknown;
+}): Metadata;
 /** Read metadata from the same content source and index used by the page. */
 declare function getDocumentMetadata({ project, slug, }: {
     project: RdxProject;
@@ -47,9 +53,10 @@ declare function RdxLayout({ children, config, bodyClassName, }: {
     config: RDXConfig;
     bodyClassName?: string;
 }): react.JSX.Element;
-declare function HomePage({ project, component, }: {
+declare function HomePage({ project, translatedComponent: TranslatedHome, messages, }: {
     project: RdxProject;
-    component?: NonNullable<RDXConfig['homepage']>['component'];
+    translatedComponent?: ComponentType<RdxTranslatedHomepageProps>;
+    messages?: Record<string, unknown>;
 }): react.JSX.Element;
 declare function NotFoundPage({ project }: {
     project: RdxProject;
@@ -59,4 +66,4 @@ declare function DocsPage({ slug, project, }: {
     project: RdxProject;
 }): Promise<react.JSX.Element>;
 
-export { DocsPage, HomePage, NotFoundPage, RdxLayout, getDocumentMarkdownResponse, getDocumentMetadata, getLlmIndexResponse, getMarkdownHref, getMarkdownPaths, getMarkdownResponse, getPageMetadata, getRdxMetadata, getRdxRobots, getRdxSitemap, getSearchResponse, getSearchSources, getSourceRobots, markdownNotFound, parseMarkdownPath };
+export { DocsPage, HomePage, NotFoundPage, RdxLayout, getDocumentMarkdownResponse, getDocumentMetadata, getHomepageMetadata, getLlmIndexResponse, getMarkdownHref, getMarkdownPaths, getMarkdownResponse, getPageMetadata, getRdxMetadata, getRdxRobots, getRdxSitemap, getSearchResponse, getSearchSources, getSourceRobots, markdownNotFound, parseMarkdownPath };

package/dist/runtime/index.js

@@ -318,6 +318,67 @@ import {
   getSourceOptions as getSourceOptions4
 } from "@lexibase/rdx-core";
 import { notFound } from "next/navigation";
+function getHomepageMetadata({
+  project,
+  locale,
+  translatedLocales,
+  metadata
+}) {
+  const { config, localization } = project;
+  if (!config.homepage?.enabled || !localization) return {};
+  const selected = localization.locales.find((entry) => entry.path === locale);
+  if (locale && (!selected || selected.code === localization.defaultLocale))
+    return {};
+  const base = config.metadata.metadataBase;
+  const primaryUrl = base ? new URL("/", base).href : void 0;
+  if (locale && !translatedLocales?.has(locale)) {
+    if (config.homepage.component) return {};
+    return {
+      robots: { index: false, follow: true },
+      ...primaryUrl ? { alternates: { canonical: primaryUrl } } : {}
+    };
+  }
+  const url = base && new URL(locale ? `/${locale}` : "/", base).href;
+  const site = getRdxMetadata(config);
+  const fields = metadata && typeof metadata === "object" ? metadata : {};
+  const title = "title" in fields && typeof fields.title === "string" ? fields.title.trim() : "";
+  const description = "description" in fields && typeof fields.description === "string" ? fields.description.trim() : "";
+  const defaults = {
+    title: config.metadata.applicationName,
+    description: config.description
+  };
+  const social = {
+    ...title ? { title: { absolute: title } } : {},
+    ...description ? { description } : {}
+  };
+  return {
+    ...social,
+    ...site.openGraph || title || description ? {
+      openGraph: {
+        ...defaults,
+        ...site.openGraph,
+        ...social,
+        ...url ? { url } : {}
+      }
+    } : {},
+    ...site.twitter || title || description ? { twitter: { ...defaults, ...site.twitter, ...social } } : {},
+    ...base && url && primaryUrl ? {
+      alternates: {
+        canonical: url,
+        languages: {
+          [localization.defaultLocale]: primaryUrl,
+          "x-default": primaryUrl,
+          ...Object.fromEntries(
+            localization.locales.filter((entry) => translatedLocales?.has(entry.path)).map((entry) => [
+              entry.code,
+              new URL(`/${entry.path}`, base).href
+            ])
+          )
+        }
+      }
+    } : {}
+  };
+}
 function getDocumentMetadata({
   project,
   slug
@@ -488,16 +549,17 @@ function RdxHeader({
 }
 function HomePage({
   project,
-  component
+  translatedComponent: TranslatedHome,
+  messages
 }) {
   const { config } = project;
   const docsHref = getDocsHref4(project);
   if (!config.homepage?.enabled) redirect(docsHref);
   const homepage = config.homepage;
-  const CustomHome = component ?? homepage.component;
+  const CustomHome = homepage.component;
   const docsLabel = getMessages(config.lang).docs;
   const source = project.sources[0];
-  const categories = CustomHome ? [] : getDocsIndex4(getSourceOptions5(project, source));
+  const categories = CustomHome || TranslatedHome ? [] : getDocsIndex4(getSourceOptions5(project, source));
   const firstPage = categories[0]?.pages[0];
   return /* @__PURE__ */ jsxs(Fragment, { children: [
     /* @__PURE__ */ jsx(RdxHeader, { project, onHomepage: true }),
@@ -507,7 +569,17 @@ function HomePage({
         id: "rdx-main",
         tabIndex: -1,
         className: "relative flex-1 min-h-0 overflow-y-auto",
-        children: CustomHome ? /* @__PURE__ */ jsx(CustomHome, { lang: config.lang, docsHref }) : /* @__PURE__ */ jsx(
+        children: CustomHome ? /* @__PURE__ */ jsx(CustomHome, { lang: config.lang, docsHref }) : TranslatedHome ? /* @__PURE__ */ jsx(
+          TranslatedHome,
+          {
+            lang: config.lang,
+            docsHref,
+            t: (text2) => {
+              const translation = messages && Object.hasOwn(messages, text2) ? messages[text2] : void 0;
+              return typeof translation === "string" && translation.trim() ? translation : text2;
+            }
+          }
+        ) : /* @__PURE__ */ jsx(
           Home,
           {
             title: homepage.title ?? config.metadata.applicationName,
@@ -810,6 +882,7 @@ export {
   createRdxProject,
   getDocumentMarkdownResponse,
   getDocumentMetadata,
+  getHomepageMetadata,
   getLlmIndexResponse,
   getLocalizedProject4 as getLocalizedProject,
   getMarkdownHref,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lexibase/rdx-next",
-  "version": "5.2.0",
+  "version": "6.0.1",
   "description": "The Next.js runtime for RDX documentation projects.",
   "license": "MIT",
   "type": "module",
@@ -52,8 +52,8 @@
     "next-mdx-remote": "^6.0.0",
     "remark-gfm": "^4",
     "typescript": "6.0.3",
-    "@lexibase/rdx-core": "3.1.1",
-    "@lexibase/rdx-types": "2.5.0"
+    "@lexibase/rdx-core": "3.2.0",
+    "@lexibase/rdx-types": "2.6.0"
   },
   "peerDependencies": {
     "@lexibase/rdx-ui": "^3.5.0",
@@ -81,9 +81,9 @@
     "next": "^16.4.2",
     "react": "19.3.1",
     "react-dom": "19.3.1",
-    "@lexibase/rdx-ui": "3.5.4",
     "@rdx/eslint-config": "1.0.0",
-    "@rdx/typescript-config": "1.0.0"
+    "@rdx/typescript-config": "1.0.0",
+    "@lexibase/rdx-ui": "3.5.5"
   },
   "scripts": {
     "dev": "tsup src/index.ts src/runtime/index.tsx --format esm --dts --watch --external @lexibase/rdx-core --external @lexibase/rdx-types --external @lexibase/rdx-ui --external next --external react --external react-dom --external next-mdx-remote",

package/templates/runtime/app/globals.css

@@ -5,4 +5,3 @@
 @source '../../components/**/*.{ts,tsx}';
 @source '../../docs/**/*.mdx';
 @source '../../locale/*/docs/**/*.mdx';
-@source '../../locale/*/home.tsx';

package/templates/runtime/app/page.tsx

@@ -1,7 +1,15 @@
-import { HomePage } from '@lexibase/rdx-next/runtime'
+import { getHomepageMetadata, HomePage } from '@lexibase/rdx-next/runtime'
 
+import { getHomepageSeo, getHomepageTranslation } from '../rdx-home'
 import { getProject } from '../rdx-project'
 
+export async function generateMetadata() {
+  return getHomepageMetadata({
+    project: await getProject(),
+    ...getHomepageSeo(),
+  })
+}
+
 export default async function Home() {
-  return <HomePage project={await getProject()} />
+  return <HomePage project={await getProject()} {...getHomepageTranslation()} />
 }

package/templates/runtime/rdx-home.ts

@@ -0,0 +1,2 @@
+export const getHomepageTranslation: (locale?: string) => object = () => ({})
+export const getHomepageSeo: (locale?: string) => object = () => ({})