@lexibase/rdx-next 6.0.0 → 6.1.0

package/bin/cli.mjs

@@ -67,6 +67,9 @@ export async function runRdxCli({ templateDir } = {}) {
       console.log(
         '  rdx add i18n [--locales en,es-ES] [--package-manager npm|pnpm|yarn]'
       )
+      console.log(
+        '  rdx i18n sync: add missing phrases to homepage translation catalogs'
+      )
       console.log(
         'Plugin commands are registered through plugins in rdx.config.ts.'
       )
@@ -86,6 +89,18 @@ export async function runRdxCli({ templateDir } = {}) {
       if (commandArgs.length) throw new Error('Usage: rdx check')
     }
 
+    const syncHomepage = command === 'i18n' && commandArgs[0] === 'sync'
+    if (
+      syncHomepage &&
+      commandArgs.length === 2 &&
+      ['--help', '-h'].includes(commandArgs[1])
+    ) {
+      console.log(
+        'Usage: rdx i18n sync\nAdd missing homepage phrases to the configured languages’ home.json files.'
+      )
+      return
+    }
+
     if (command === 'add') {
       if (
         (commandArgs.length === 1 &&
@@ -145,6 +160,16 @@ export async function runRdxCli({ templateDir } = {}) {
       rootDir: projectRoot,
       command,
     })
+    if (
+      syncHomepage &&
+      !project.commands.some((entry) => entry.name === 'i18n')
+    ) {
+      if (commandArgs.length !== 1) throw new Error('Usage: rdx i18n sync')
+      const { syncHomepageTranslations } =
+        await import('./homepage-translations.mjs')
+      await syncHomepageTranslations(project)
+      return
+    }
     let homepageTranslations
     if (
       project.config.homepage?.enabled &&

package/bin/homepage-translations.mjs

@@ -1,4 +1,12 @@
-import { readFile, writeFile } from 'node:fs/promises'
+import { randomUUID } from 'node:crypto'
+import {
+  lstat,
+  readFile,
+  realpath,
+  rename,
+  rm,
+  writeFile,
+} from 'node:fs/promises'
 import path from 'node:path'
 
 const sourceFile = 'components/home.tsx'
@@ -16,12 +24,17 @@ async function readOptional(file) {
   }
 }
 
-async function sourcePhrases(rootDir) {
+async function sourcePhrases(rootDir, report) {
   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)
+  const file = ts.createSourceFile(
+    sourceFile,
+    source,
+    ts.ScriptTarget.Latest,
+    true
+  )
   for (const statement of file.statements) {
     if (
       !ts.isExpressionStatement(statement) ||
@@ -34,19 +47,170 @@ async function sourcePhrases(rootDir) {
       )
   }
   const phrases = new Set()
-  function visit(node) {
+  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.isCallExpression(node) &&
-      ts.isIdentifier(node.expression) &&
-      node.expression.text === 't' &&
-      node.arguments.length === 1 &&
-      ts.isStringLiteralLike(node.arguments[0])
-    )
-      phrases.add(node.arguments[0].text)
+      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
+  if (report) {
+    for (const { line, message } of warnings.sort((a, b) => a.line - b.line))
+      console.warn(`[RDX] ${sourceFile}:${line}: ${message}`)
+  }
+  phrases.delete(metadataKey)
+  return { phrases, warnings }
+}
+
+function parseCatalog(raw) {
+  const parsed = JSON.parse(raw)
+  if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed))
+    throw new Error('Expected a JSON object.')
+  return parsed
+}
+
+export async function syncHomepageTranslations(project) {
+  const { rootDir, config } = project
+  const locales = project.sources.find((source) => source.id === 'current')
+    ?.localization?.locales
+  if (!locales)
+    throw new Error('Enable the i18n plugin before running rdx i18n sync.')
+  if (!config.homepage?.enabled || !config.homepage.translations)
+    throw new Error(
+      'Set homepage.enabled and homepage.translations to true before running rdx i18n sync.'
+    )
+
+  const { phrases } = await sourcePhrases(rootDir, true)
+  if (!phrases.size) {
+    console.log(`[RDX] No literal homepage phrases found in ${sourceFile}.`)
+    return
+  }
+  const root = await realpath(rootDir)
+  const updates = []
+  for (const { folder } of locales) {
+    if (!folder) continue
+    const file = `locale/${folder}/home.json`
+    const directory = await realpath(path.join(root, 'locale', folder))
+    const relative = path.relative(root, directory)
+    if (
+      !relative ||
+      relative === '..' ||
+      relative.startsWith(`..${path.sep}`) ||
+      path.isAbsolute(relative)
+    )
+      throw new Error(`${file} must remain inside the project.`)
+    const target = path.join(directory, 'home.json')
+    const info = await lstat(target).catch((error) => {
+      if (!missingFile(error)) throw error
+    })
+    if (info && !info.isFile())
+      throw new Error(`${file} must be a regular file.`)
+    const raw = info ? await readFile(target, 'utf8') : undefined
+    let messages = {}
+    if (raw !== undefined) {
+      try {
+        messages = parseCatalog(raw)
+      } catch {
+        throw new Error(
+          `Cannot sync ${file}: expected a JSON object of homepage phrases.`
+        )
+      }
+    }
+    const missing = [...phrases].filter(
+      (phrase) => !Object.hasOwn(messages, phrase)
+    )
+    if (missing.length)
+      updates.push({
+        file,
+        target,
+        info,
+        raw,
+        count: missing.length,
+        messages: Object.fromEntries([
+          ...Object.entries(messages),
+          ...missing.map((phrase) => [phrase, '']),
+        ]),
+      })
+  }
+
+  for (const { file, target, info, raw, count, messages } of updates) {
+    const content = JSON.stringify(messages, null, 2) + '\n'
+    if (raw === undefined) {
+      await writeFile(target, content, { flag: 'wx' })
+    } else {
+      const temporary = `${target}.${randomUUID()}.tmp`
+      try {
+        await writeFile(temporary, content, { flag: 'wx', mode: info.mode })
+        if (
+          !(await lstat(target)).isFile() ||
+          (await readFile(target, 'utf8')) !== raw
+        )
+          throw new Error(
+            `${file} changed during sync. Run rdx i18n sync again.`
+          )
+        await rename(temporary, target)
+      } finally {
+        await rm(temporary, { force: true })
+      }
+    }
+    console.log(
+      `[RDX] ${file}: added ${count} ${count === 1 ? 'phrase' : 'phrases'}.`
+    )
+  }
+  if (!updates.length) console.log('[RDX] Homepage catalogs are up to date.')
 }
 
 export async function readHomepageTranslations(
@@ -54,8 +218,7 @@ export async function readHomepageTranslations(
   { report = false } = {}
 ) {
   const { rootDir, localization } = project
-  const phrases = await sourcePhrases(rootDir)
-  phrases.delete(metadataKey)
+  const { phrases, warnings } = await sourcePhrases(rootDir, report)
   const catalogs = []
   for (const locale of localization?.locales ?? []) {
     if (!locale.folder) continue
@@ -64,10 +227,7 @@ export async function readHomepageTranslations(
     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
+        messages = parseCatalog(raw)
         catalogs.push({ file, locale: locale.path })
       } catch {
         console.warn(
@@ -86,11 +246,14 @@ export async function readHomepageTranslations(
           `[RDX] ${file}: missing translation for ${JSON.stringify(phrase)}`
         )
     }
-    for (const phrase of Object.keys(messages)) {
-      if (phrase !== metadataKey && !phrases.has(phrase))
-        console.warn(
-          `[RDX] ${file}: orphaned 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 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lexibase/rdx-next",
-  "version": "6.0.0",
+  "version": "6.1.0",
   "description": "The Next.js runtime for RDX documentation projects.",
   "license": "MIT",
   "type": "module",
@@ -82,8 +82,8 @@
     "react": "19.3.1",
     "react-dom": "19.3.1",
     "@rdx/eslint-config": "1.0.0",
-    "@rdx/typescript-config": "1.0.0",
-    "@lexibase/rdx-ui": "3.5.5"
+    "@lexibase/rdx-ui": "3.5.6",
+    "@rdx/typescript-config": "1.0.0"
   },
   "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",