feat(i18n): add en.meta.json generation script

Author: shuuji3

package.json

@@ -20,6 +20,7 @@
     "i18n:report": "node scripts/find-invalid-translations.ts",
     "i18n:report:fix": "node scripts/remove-unused-translations.ts",
     "i18n:schema": "node scripts/generate-i18n-schema.ts",
+    "i18n:meta:update-en-meta": "node scripts/i18n-meta/cli.ts update-en-meta",
     "knip": "knip",
     "knip:fix": "knip --fix",
     "lint": "oxlint && oxfmt --check",
@@ -126,6 +127,7 @@
     "@storybook/addon-a11y": "catalog:storybook",
     "@storybook/addon-docs": "catalog:storybook",
     "@storybook/addon-themes": "catalog:storybook",
+    "@types/dot-object": "2.1.6",
     "@types/node": "24.10.13",
     "@types/sanitize-html": "2.16.0",
     "@types/semver": "7.7.1",
@@ -136,6 +138,7 @@
     "chromatic": "15.1.0",
     "defu": "6.1.4",
     "devalue": "5.6.3",
+    "dot-object": "2.1.5",
     "eslint-plugin-regexp": "3.0.0",
     "fast-check": "4.5.3",
     "h3": "1.15.5",

pnpm-lock.yaml

@@ -0,0 +1,20 @@
+import { parseArgs } from 'node:util'
+import { updateEnMetaJson } from './update-en-meta-json.ts'
+
+function showHelp() {
+  const scriptName = process.env.npm_lifecycle_event || 'node scripts/i18n-meta/cli.ts'
+  console.log(`Usage: pnpm run ${scriptName} update-en-meta`)
+}
+
+function main() {
+  const { positionals } = parseArgs({ allowPositionals: true })
+
+  if (positionals[0] !== 'update-en-meta') {
+    showHelp()
+    return
+  }
+
+  updateEnMetaJson()
+}
+
+main()

scripts/i18n-meta/cli.ts

@@ -0,0 +1,58 @@
+import { execSync } from 'node:child_process'
+import * as fs from 'node:fs'
+import type { EnJson, EnMetaJson } from './types.d.ts'
+
+export function git(command: string) {
+  try {
+    return execSync(`git ${command}`, { encoding: 'utf-8' }).trim()
+  } catch {
+    console.error(`🚨 Git command failed: git ${command}`)
+    return null
+  }
+}
+
+function readJson<T>(filePath: string): T {
+  return JSON.parse(fs.readFileSync(filePath, 'utf-8')) as T
+}
+
+export function getCurrentCommitHash() {
+  return git('rev-parse HEAD')
+}
+
+export function getNewEnJson(enJsonPath: string): EnJson {
+  if (fs.existsSync(enJsonPath)) {
+    return readJson<EnMetaJson>(enJsonPath)
+  }
+  return {} as EnMetaJson
+}
+
+export function getOldEnMetaJson(enMetaJsonPath: string): EnMetaJson {
+  if (fs.existsSync(enMetaJsonPath)) {
+    return readJson<EnMetaJson>(enMetaJsonPath)
+  }
+  return {} as EnMetaJson
+}
+
+function omitMeta<T extends object>(obj: T): Omit<T, '$meta'> {
+  const { $meta: _, ...rest } = obj as T & { $meta?: unknown }
+  return rest
+}
+
+export function checkTranslationChanges(oldMeta: EnMetaJson, newMeta: EnMetaJson): boolean {
+  const oldObj = omitMeta(oldMeta)
+  const newObj = omitMeta(newMeta)
+  return JSON.stringify(oldObj) !== JSON.stringify(newObj)
+}
+
+export function createUpdatedEnMetaJson(
+  commitHash: string | null,
+  content: EnMetaJson,
+): EnMetaJson {
+  return {
+    $meta: {
+      last_updated_commit: commitHash,
+      updated_at: new Date().toISOString(),
+    },
+    ...content,
+  } as EnMetaJson
+}

scripts/i18n-meta/git-utils.ts

@@ -0,0 +1,16 @@
+export type EnJson = {
+  [key: string]: string | EnJson
+}
+
+export type MetaEntry = {
+  text: string
+  commit: string
+}
+
+export type EnMetaJson = {
+  $meta?: {
+    last_updated_commit: string
+    updated_at: string
+  }
+  [key: string]: string | MetaEntry | EnMetaJson
+}

scripts/i18n-meta/types.d.ts

@@ -0,0 +1,62 @@
+import { writeFileSync } from 'node:fs'
+import { resolve } from 'node:path'
+import dot from 'dot-object'
+import {
+  checkTranslationChanges,
+  createUpdatedEnMetaJson,
+  getCurrentCommitHash,
+  getNewEnJson,
+  getOldEnMetaJson,
+} from './git-utils.ts'
+import type { EnJson, EnMetaJson, MetaEntry } from './types.d.ts'
+
+const enJsonPath = resolve('i18n/locales/en.json')
+const enMetaJsonPath = resolve('i18n/locales/en.meta.json')
+
+/**
+ * Update a metadata JSON file for English translations.
+ */
+export function updateEnMetaJson() {
+  const newEnJson = getNewEnJson(enJsonPath)
+  const oldEnMetaJson = getOldEnMetaJson(enMetaJsonPath)
+
+  const currentCommitHash = getCurrentCommitHash()
+  const enMetaJson = currentCommitHash
+    ? makeEnMetaJson(newEnJson, oldEnMetaJson, currentCommitHash)
+    : ({} as EnMetaJson)
+
+  const hasChanges = checkTranslationChanges(oldEnMetaJson, enMetaJson)
+  if (!hasChanges) {
+    console.info('ℹ️ No translation changes – en.meta.json left untouched')
+    return
+  }
+
+  const finalMeta = createUpdatedEnMetaJson(currentCommitHash, enMetaJson)
+
+  writeFileSync(enMetaJsonPath, JSON.stringify(finalMeta, null, 2) + '\n', 'utf-8')
+  console.log(`✅ Updated en.meta.json – last_updated_commit: ${currentCommitHash}`)
+}
+
+export function makeEnMetaJson(
+  newEnJson: EnJson,
+  oldMetaEnJson: EnMetaJson,
+  latestCommitHash: string,
+): EnMetaJson {
+  const newFlat = dot.dot(newEnJson) as Record<string, string>
+  const oldMetaFlat = dot.dot(oldMetaEnJson) as Record<string, string>
+  const metaFlat: Record<string, MetaEntry> = {}
+
+  for (const key in newFlat) {
+    const newText = newFlat[key]
+
+    const lastSeenText = oldMetaFlat[`${key}.text`]
+    const lastCommit = oldMetaFlat[`${key}.commit`]
+
+    if (newText === lastSeenText) {
+      metaFlat[key] = { text: newText, commit: lastCommit ?? latestCommitHash }
+    } else {
+      metaFlat[key] = { text: newText, commit: latestCommitHash }
+    }
+  }
+  return dot.object(metaFlat) as EnMetaJson
+}

scripts/i18n-meta/update-en-meta-json.ts

@@ -0,0 +1,16 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "nodenext",
+    "strict": true,
+    "esModuleInterop": true,
+    "skipLibCheck": true,
+    "noEmit": true,
+    "allowImportingTsExtensions": true,
+    "declaration": true,
+    "types": ["node"],
+    "declarationMap": true
+  },
+  "include": ["**/*.ts"],
+  "exclude": ["node_modules", "dist"]
+}

scripts/tsconfig.json

@@ -0,0 +1,118 @@
+import { describe, expect, it } from 'vitest'
+import { makeEnMetaJson } from '#scripts/i18n-meta/update-en-meta-json'
+
+describe('Create en.meta.json', () => {
+  it('should handle an empty en.json file', () => {
+    const newEnJson = {}
+    const oldEnMetaJson = {}
+
+    const enMetaJson = makeEnMetaJson(newEnJson, oldEnMetaJson, 'sha-new-12345')
+    expect(enMetaJson).toEqual({})
+  })
+
+  it('should generate en.meta.json correctly for an initial en.json', () => {
+    const newEnJson = {
+      tagline: 'npmx - a fast, modern browser for the npm registry',
+    }
+    const oldEnMetaJson = {}
+
+    const enMetaJson = makeEnMetaJson(newEnJson, oldEnMetaJson, 'sha-new-12345')
+    expect(enMetaJson).toEqual({
+      tagline: {
+        text: 'npmx - a fast, modern browser for the npm registry',
+        commit: 'sha-new-12345',
+      },
+    })
+  })
+
+  it('should update existing keys and add new keys with the latest commit hash', () => {
+    const newEnJson = {
+      name: 'npmx',
+      tagline: 'npmx - a fast, modern browser for the npm registry',
+      description: 'Search, browse, and explore packages with a modern interface.',
+    }
+    const oldEnMetaJson = {
+      name: {
+        text: 'npmx',
+        commit: 'sha-old-12345',
+      },
+      tagline: {
+        text: 'npmx - a better browser for the npm registry',
+        commit: 'sha-old-12345',
+      },
+    }
+
+    const enMetaJson = makeEnMetaJson(newEnJson, oldEnMetaJson, 'sha-new-12345')
+    expect(enMetaJson).toEqual({
+      name: {
+        text: 'npmx',
+        commit: 'sha-old-12345',
+      },
+      tagline: {
+        text: 'npmx - a fast, modern browser for the npm registry',
+        commit: 'sha-new-12345',
+      },
+      description: {
+        text: 'Search, browse, and explore packages with a modern interface.',
+        commit: 'sha-new-12345',
+      },
+    })
+  })
+
+  it('should remove keys that are no longer in en.json', () => {
+    const newEnJson = {
+      tagline: 'npmx - a fast, modern browser for the npm registry',
+    }
+    const oldEnMetaJson = {
+      tagline: {
+        text: 'npmx - a fast, modern browser for the npm registry',
+        commit: 'sha-old-12345',
+      },
+      toBeRemoved: { text: 'This will be gone', commit: 'sha-old-12345' },
+    }
+
+    const enMetaJson = makeEnMetaJson(newEnJson, oldEnMetaJson, 'sha-new-12345')
+    expect(enMetaJson).toEqual({
+      tagline: {
+        text: 'npmx - a fast, modern browser for the npm registry',
+        commit: 'sha-old-12345',
+      },
+    })
+  })
+
+  it('should handle complex nested structures', () => {
+    const newEnJson = {
+      a: {
+        b: 'updated-value',
+      },
+      c: 'value-c',
+      d: 'added-value',
+    }
+
+    const oldEnMetaJson = {
+      a: {
+        b: {
+          text: 'value-b',
+          commit: 'sha-old-12345',
+        },
+      },
+      c: {
+        text: 'value-c',
+        commit: 'sha-old-12345',
+      },
+      d: {
+        text: 'added-value',
+        commit: 'sha-new-12345',
+      },
+    }
+
+    const enMetaJson = makeEnMetaJson(newEnJson, oldEnMetaJson, 'sha-new-12345')
+    expect(enMetaJson).toEqual({
+      a: {
+        b: { text: 'updated-value', commit: 'sha-new-12345' },
+      },
+      c: { text: 'value-c', commit: 'sha-old-12345' },
+      d: { text: 'added-value', commit: 'sha-new-12345' },
+    })
+  })
+})

test/unit/scripts/generate-en-meta-json.spec.ts

@@ -13,6 +13,7 @@ export default defineConfig({
           alias: {
             '#shared': `${rootDir}/shared`,
             '#server': `${rootDir}/server`,
+            '#scripts': `${rootDir}/scripts`,
           },
         },
         test: {