create-bubbles 0.1.26 → 0.1.28

package/template-vp-monorepo-react-nestjs/packages/i18n/cli/src/scanner.test.ts

@@ -21,6 +21,94 @@ describe('scanSource', () => {
     expect(scanSource(source)).toEqual([{ key: '你好 {name}', index: 16, line: 1, column: 17 }])
   })
 
+  it.each([
+    { boundary: 'call name', source: "tr/* 调用说明 */('保存')" },
+    { boundary: 'opening parenthesis', source: "tr(/* 参数说明 */ '保存')" },
+    { boundary: 'closing parenthesis', source: "tr('保存' /* 词条说明 */)" },
+    { boundary: 'comma', source: "tr('保存' /* 词条说明 */, { name })" },
+    {
+      boundary: 'adjacent mixed comments',
+      source: [
+        'tr/**/// 调用说明',
+        '(/* 参数说明 */ /**/ // 参数说明',
+        "  '保存' /**/ // 词条说明",
+        '  /* 词条说明 */)',
+      ].join('\n'),
+    },
+  ])('allows comments at the $boundary boundary', ({ source }) => {
+    expect(scanSource(source)).toEqual([{ key: '保存', index: 0, line: 1, column: 1 }])
+  })
+
+  it.each([
+    { name: 'LF', lineEnding: '\n' },
+    { name: 'CR', lineEnding: '\r' },
+    { name: 'CRLF', lineEnding: '\r\n' },
+    { name: 'U+2028', lineEnding: '\u2028' },
+    { name: 'U+2029', lineEnding: '\u2029' },
+  ])('ends line comments at $name and preserves source positions', ({ lineEnding }) => {
+    const source = [
+      'tr // 调用说明',
+      '  (// 参数说明',
+      "    'first' // 词条说明",
+      '  )',
+      "  tr('next')",
+    ].join(lineEnding)
+
+    expect(scanSource(source)).toEqual([
+      { key: 'first', index: 0, line: 1, column: 1 },
+      { key: 'next', index: source.indexOf("tr('next')"), line: 5, column: 3 },
+    ])
+  })
+
+  it('preserves comment markers inside static strings', () => {
+    const source = [
+      "tr('https://example.test/path/*说明*/')",
+      'tr("/* 开头 */ // 结尾")',
+      'tr(`// 第一行\n/* 第二行 */`)',
+    ].join('\n')
+
+    expect(scanSource(source).map(({ key }) => key)).toEqual([
+      'https://example.test/path/*说明*/',
+      '/* 开头 */ // 结尾',
+      '// 第一行\n/* 第二行 */',
+    ])
+  })
+
+  it('continues extracting complete calls inside comments and ordinary strings', () => {
+    const source = [
+      "// tr('行注释')",
+      "/* tr('块注释') */",
+      'const example = "tr(\'字符串\')"',
+    ].join('\r\n')
+
+    expect(scanSource(source)).toEqual([
+      { key: '行注释', index: 3, line: 1, column: 4 },
+      { key: '块注释', index: source.indexOf("tr('块注释')"), line: 2, column: 4 },
+      { key: '字符串', index: source.indexOf("tr('字符串')"), line: 3, column: 18 },
+    ])
+  })
+
+  it('still rejects dynamic expressions around comments', () => {
+    const source = [
+      'tr(/* 参数说明 */ key)',
+      "tr('a' /* 词条说明 */ + value)",
+      "tr('a' // 词条说明\n + value)",
+      "tr('a' /* 词条说明 */.trim())",
+      "tr('a' /* 词条说明 */ / divisor)",
+      'tr(`hello ${name}` /* 词条说明 */)',
+    ].join('\n')
+
+    expect(scanSource(source)).toEqual([])
+  })
+
+  it.each([
+    { boundary: 'call name', source: "tr/* 调用说明 ('保存')" },
+    { boundary: 'opening parenthesis', source: "tr(/* 参数说明 '保存')" },
+    { boundary: 'static string', source: "tr('保存' /* 词条说明)" },
+  ])('rejects an unterminated block comment after the $boundary', ({ source }) => {
+    expect(scanSource(source)).toEqual([])
+  })
+
   it('decodes common escapes without evaluating source code', () => {
     const source = String.raw`tr('It\'s\n中\t\x41\u6587\u{1F600}')`
 

package/template-vp-monorepo-react-nestjs/packages/i18n/cli/src/scanner.ts

@@ -21,8 +21,10 @@ interface ParsedEscape {
 
 const identifierContinuePattern = /[\p{ID_Continue}_$]/u
 const whitespacePattern = /\s/u
+const lineTerminatorPattern = /[\n\r\u2028\u2029]/u
 const hexPattern = /^[\dA-Fa-f]+$/
 
+/** 扫描文本中的翻译调用及其静态字符串参数，允许调用边界的空白与注释；返回原始源码行列位置，跳过插值模板和动态表达式。 */
 export function scanSource(source: string, options: ScanOptions = {}): MessageOccurrence[] {
   const callNames = normalizeCallNames(options.callNames)
   const occurrences: MessageOccurrence[] = []
@@ -43,12 +45,12 @@ export function scanSource(source: string, options: ScanOptions = {}): MessageOc
         continue
       }
 
-      let cursor = skipWhitespace(source, index + callName.length)
+      let cursor = skipWhitespaceAndComments(source, index + callName.length)
       if (source[cursor] !== '(') {
         continue
       }
 
-      cursor = skipWhitespace(source, cursor + 1)
+      cursor = skipWhitespaceAndComments(source, cursor + 1)
       const quote = source[cursor]
       if (quote !== "'" && quote !== '"' && quote !== '`') {
         continue
@@ -59,7 +61,7 @@ export function scanSource(source: string, options: ScanOptions = {}): MessageOc
         continue
       }
 
-      const nextTokenIndex = skipWhitespace(source, parsed.endIndex)
+      const nextTokenIndex = skipWhitespaceAndComments(source, parsed.endIndex)
       const nextToken = source[nextTokenIndex]
       if (nextToken !== ',' && nextToken !== ')') {
         continue
@@ -81,6 +83,7 @@ export function scanSource(source: string, options: ScanOptions = {}): MessageOc
   return occurrences
 }
 
+/** 去除空调用名和重复项，并优先匹配更长的名称；未配置时使用 tr。 */
 function normalizeCallNames(callNames: readonly string[] | undefined): string[] {
   const names = callNames ?? ['tr']
   return [...new Set(names.filter((name) => name.length > 0))].sort(
@@ -88,6 +91,7 @@ function normalizeCallNames(callNames: readonly string[] | undefined): string[]
   )
 }
 
+/** 检查候选调用名的两侧，避免把较长标识符中的片段识别为翻译函数。 */
 function hasIdentifierBoundaries(source: string, index: number, callName: string): boolean {
   const firstCharacter = callName[0]
   const lastCharacter = callName[callName.length - 1]
@@ -101,6 +105,7 @@ function hasIdentifierBoundaries(source: string, index: number, callName: string
   )
 }
 
+/** 判断字符是否可以继续组成 JavaScript 标识符，兼容 Unicode 连接字符。 */
 function isIdentifierContinue(character: string | undefined): boolean {
   return (
     character !== undefined &&
@@ -110,14 +115,38 @@ function isIdentifierContinue(character: string | undefined): boolean {
   )
 }
 
-function skipWhitespace(source: string, startIndex: number): number {
+/** 跳过调用边界的空白、行注释和块注释；未闭合块注释返回源码末尾，使当前候选匹配失败。 */
+function skipWhitespaceAndComments(source: string, startIndex: number): number {
   let index = startIndex
-  while (index < source.length && whitespacePattern.test(source[index] ?? '')) {
-    index += 1
+  while (index < source.length) {
+    if (whitespacePattern.test(source[index] ?? '')) {
+      index += 1
+      continue
+    }
+
+    if (source.startsWith('//', index)) {
+      index += 2
+      while (index < source.length && !lineTerminatorPattern.test(source[index] ?? '')) {
+        index += 1
+      }
+      continue
+    }
+
+    if (source.startsWith('/*', index)) {
+      const closingIndex = source.indexOf('*/', index + 2)
+      if (closingIndex === -1) {
+        return source.length
+      }
+      index = closingIndex + 2
+      continue
+    }
+
+    break
   }
   return index
 }
 
+/** 解析引号包裹的静态词条并还原转义；未闭合、非法换行或包含模板插值时返回 undefined。 */
 function parseString(
   source: string,
   startIndex: number,
@@ -125,7 +154,7 @@ function parseString(
 ): ParsedString | undefined {
   let value = ''
 
-  for (let index = startIndex + 1; index < source.length; ) {
+  for (let index = startIndex + 1; index < source.length;) {
     const character = source[index]
 
     if (character === quote) {
@@ -157,6 +186,7 @@ function parseString(
   return undefined
 }
 
+/** 解析反斜杠后的字符转义、续行和 Unicode 转义，返回解码结果与后续扫描位置。 */
 function parseEscape(source: string, slashIndex: number): ParsedEscape | undefined {
   const escaped = source[slashIndex + 1]
   if (escaped === undefined) {
@@ -208,6 +238,7 @@ function parseEscape(source: string, slashIndex: number): ParsedEscape | undefin
   return { value: escaped, nextIndex: slashIndex + 2 }
 }
 
+/** 解码指定长度的十六进制转义；位数不足或包含非十六进制字符时返回 undefined。 */
 function parseFixedHexEscape(
   source: string,
   slashIndex: number,
@@ -226,6 +257,7 @@ function parseFixedHexEscape(
   }
 }
 
+/** 解码花括号包裹的 Unicode 码点，并拒绝缺失括号或超出 Unicode 范围的值。 */
 function parseCodePointEscape(source: string, slashIndex: number): ParsedEscape | undefined {
   const digitsStart = slashIndex + 3
   const closingBraceIndex = source.indexOf('}', digitsStart)
@@ -249,6 +281,7 @@ function parseCodePointEscape(source: string, slashIndex: number): ParsedEscape
   }
 }
 
+/** 收集每行起始偏移，兼容 LF、CRLF、CR 以及 Unicode 行和段落分隔符。 */
 function collectLineStarts(source: string): number[] {
   const starts = [0]
 
@@ -258,7 +291,7 @@ function collectLineStarts(source: string): number[] {
         index += 1
       }
       starts.push(index + 1)
-    } else if (source[index] === '\n') {
+    } else if (lineTerminatorPattern.test(source[index] ?? '')) {
       starts.push(index + 1)
     }
   }
@@ -266,6 +299,7 @@ function collectLineStarts(source: string): number[] {
   return starts
 }
 
+/** 使用二分查找将字符偏移转换为从 1 开始的行号与列号。 */
 function locatePosition(
   lineStarts: readonly number[],
   index: number,

package/template-vp-monorepo-react-nestjs/packages/i18n/cli/src/sync.ts

@@ -58,6 +58,7 @@ const defaultFormat: CatalogFormat = {
   trailingEol: true,
 }
 
+/** 校验并计算单个语言包的词条差异，按 dryRun 选项决定是否写入并返回变更报告。 */
 export async function syncCatalog(options: SyncCatalogOptions): Promise<SyncFileReport> {
   const keys = normalizeKeys(options.keys)
   const plan = await planCatalog(options, keys)
@@ -69,6 +70,7 @@ export async function syncCatalog(options: SyncCatalogOptions): Promise<SyncFile
   return plan.report
 }
 
+/** 先校验项目内全部语言包，再按需并行写入各文件；写入原子性以单文件为单位。 */
 export async function syncProject(options: SyncProjectOptions): Promise<SyncFileReport[]> {
   const keys = normalizeKeys(options.keys)
   const plans = await Promise.all(
@@ -97,6 +99,7 @@ export async function syncProject(options: SyncProjectOptions): Promise<SyncFile
   return plans.map((plan) => plan.report)
 }
 
+/** 读取语言包并生成保留翻译的增删计划；拒绝相对路径及未经允许的空扫描清理。 */
 async function planCatalog(
   options: SyncCatalogOptions,
   keys: ReadonlySet<string>,
@@ -145,6 +148,7 @@ async function planCatalog(
   }
 }
 
+/** 读取并校验扁平字符串语言包，同时记录原格式；文件缺失时返回空词条与默认格式。 */
 async function readCatalog(path: string): Promise<CatalogState> {
   let source: string
 
@@ -197,6 +201,7 @@ async function readCatalog(path: string): Promise<CatalogState> {
   }
 }
 
+/** 检测语言包的 BOM、换行符、缩进和末尾换行，以便写回时沿用。 */
 function detectFormat(source: string): CatalogFormat {
   const bom = source.startsWith('\uFEFF')
   const json = bom ? source.slice(1) : source
@@ -212,6 +217,7 @@ function detectFormat(source: string): CatalogFormat {
   }
 }
 
+/** 按照检测到的文件格式序列化词条，恢复 BOM、换行符和末尾换行。 */
 function serializeCatalog(messages: Record<string, string>, format: CatalogFormat): string {
   const serialized = JSON.stringify(messages, undefined, format.indent) ?? '{}'
   const withEol = format.eol === '\n' ? serialized : serialized.split('\n').join(format.eol)
@@ -220,6 +226,7 @@ function serializeCatalog(messages: Record<string, string>, format: CatalogForma
   return format.bom ? `\uFEFF${withTrailingEol}` : withTrailingEol
 }
 
+/** 先写入同目录临时文件，再重命名替换目标；失败时尝试清理临时文件并传播异常。 */
 async function writeAtomic(path: string, content: string): Promise<void> {
   const directory = dirname(path)
   const temporaryPath = join(directory, `.${basename(path)}.${process.pid}.${randomUUID()}.tmp`)
@@ -235,6 +242,7 @@ async function writeAtomic(path: string, content: string): Promise<void> {
   }
 }
 
+/** 将扫描词条去重，并在包含非字符串键时抛出 TypeError。 */
 function normalizeKeys(keys: Iterable<string>): ReadonlySet<string> {
   const normalized = new Set<string>()
 
@@ -249,18 +257,22 @@ function normalizeKeys(keys: Iterable<string>): ReadonlySet<string> {
   return normalized
 }
 
+/** 按字符串比较顺序原地排序词条，使报告顺序不依赖运行环境的语言设置。 */
 function sortKeys(keys: string[]): string[] {
   return keys.sort((left, right) => (left < right ? -1 : left > right ? 1 : 0))
 }
 
+/** 判断错误是否带有可读取的文件系统错误码。 */
 function isNodeError(error: unknown): error is NodeJS.ErrnoException {
   return error instanceof Error && 'code' in error
 }
 
+/** 将未知异常转换为可输出的错误文本。 */
 function errorMessage(error: unknown): string {
   return error instanceof Error ? error.message : String(error)
 }
 
+/** 生成语言包校验错误中的值类型描述，单独区分 null 和数组。 */
 function valueType(value: unknown): string {
   if (value === null) {
     return 'null'

package/template-vp-monorepo-react-nestjs/packages/i18n/cli/test/command.test.ts

@@ -62,6 +62,42 @@ describe('runCli', () => {
     expect(output.join('\n')).toContain('Project web: 1 source files, 2 keys.')
   })
 
+  it('keeps translations for calls with comments when cleaning catalogs', async () => {
+    const root = temporaryDirectory.path
+    await mkdir(join(root, 'src'), { recursive: true })
+    await mkdir(join(root, 'locales'), { recursive: true })
+    await writeFile(
+      join(root, 'src', 'app.ts'),
+      "tr('正常')\ntr(/* 参数说明 */ '保留' /* 结束说明 */)\n",
+      'utf8',
+    )
+    await writeFile(
+      join(root, 'locales', 'en_US.json'),
+      JSON.stringify({ 正常: 'Normal', 保留: 'Keep translation', 废弃: 'Remove translation' }),
+      'utf8',
+    )
+    await writeFile(join(root, 'locales', 'zh_CN.json'), '{}\n', 'utf8')
+    await writeConfig(root)
+
+    await expect(runCli(['sync', '--clean'], { cwd: root, stdout: () => undefined })).resolves.toBe(
+      0,
+    )
+    expect(JSON.parse(await readFile(join(root, 'locales', 'en_US.json'), 'utf8'))).toEqual({
+      正常: 'Normal',
+      保留: 'Keep translation',
+    })
+    const report = JSON.parse(await readFile(join(root, '.reports', 'i18n.json'), 'utf8'))
+    expect(report.files).toEqual(
+      expect.arrayContaining([
+        expect.objectContaining({
+          locale: 'en_US',
+          deleted: ['废弃'],
+          unchangedCount: 2,
+        }),
+      ]),
+    )
+  })
+
   it('checks without writing and can fail on unused keys', async () => {
     const root = temporaryDirectory.path
     await mkdir(join(root, 'src'), { recursive: true })
@@ -189,6 +225,7 @@ describe('runCli', () => {
   })
 })
 
+/** 在测试根目录写入 ESM 配置，声明源码扫描规则、两种语言包及同步报告路径。 */
 async function writeConfig(root: string): Promise<void> {
   await writeFile(
     join(root, 'i18n.config.mjs'),

package/template-vp-monorepo-react-nestjs/packages/i18n/cli/test/temporary-directory.ts

@@ -4,6 +4,11 @@ import { join } from 'node:path'
 
 import { afterEach, beforeEach } from 'vite-plus/test'
 
+/**
+ * 注册测试生命周期钩子，在每个用例开始前创建独立临时目录，结束后递归清理其中的文件。
+ *
+ * @returns 通过 getter 动态读取当前用例目录路径的对象。
+ */
 export function useTemporaryDirectory(): { readonly path: string } {
   let path = ''
 

package/template-vp-monorepo-react-nestjs/packages/i18n/core/src/format.ts

@@ -1,5 +1,6 @@
 export type MessageValues = Record<string, string | number>
 
+/** 替换消息中的 `{key}` 占位符；未提供对应值时保留原占位符。 */
 export function formatMessage(message: string, values?: MessageValues): string {
   if (!values) return message
 

package/template-vp-monorepo-react-nestjs/packages/i18n/core/src/i18n.ts

@@ -13,6 +13,11 @@ import type {
 
 const emptyMessageLoader: LoadMessages = async () => undefined
 
+/**
+ * 创建国际化状态容器，提供翻译、异步切换语言和可选的语言偏好持久化。
+ * 接收初始语言和词条，以及可选的词条加载器、存储与存储键。
+ * @returns 可被 React 或 Vue 适配层订阅的国际化容器。
+ */
 export const createI18n = ({
   locale,
   message = {},
@@ -24,8 +29,10 @@ export const createI18n = ({
     {
       locale,
       message,
+      /** 使用当前词条翻译并插值；词条缺失时回退到原始键。 */
       tr: (key: string, values?: MessageValues): string =>
         formatMessage(store.getState().message[key] ?? key, values),
+      /** 加载目标语言后更新状态；加载失败时记录警告并切换为空词条。 */
       loadLocale: async (nextLocale) => {
         let nextMessages: Messages = {}
         try {
@@ -40,6 +47,7 @@ export const createI18n = ({
         }))
       },
     },
+    /** 状态变化后持久化当前语言，供下次初始化恢复偏好。 */
     ({ newState }) => {
       if (storage && storageKey) storage.setItem(storageKey, newState.locale)
     },
@@ -48,6 +56,11 @@ export const createI18n = ({
   return store
 }
 
+/**
+ * 优先恢复持久化的语言偏好，加载首屏词条后创建国际化容器。
+ * @param options 默认语言、词条加载器和可选的持久化配置。
+ * @returns 完成初始词条加载的容器；加载失败时使用空词条。
+ */
 export async function initI18n(options: I18nInitOptions = {}): Promise<I18nStore> {
   const { storageKey, storage, locale: defaultLocale, loaderMessage } = options
   const loadMessages = loaderMessage ?? emptyMessageLoader
@@ -67,6 +80,7 @@ export async function initI18n(options: I18nInitOptions = {}): Promise<I18nStore
 export const createI18nStore = createI18n
 
 export class i18n {
+  /** 保留类式初始化入口，等待初始语言加载完成后返回容器。 */
   static init(options?: I18nInitOptions): Promise<I18nStore> {
     return initI18n(options)
   }

package/template-vp-monorepo-react-nestjs/packages/i18n/core/src/storage.ts

@@ -10,7 +10,13 @@ export interface JsonStorage {
   removeItem: (key: string) => void
 }
 
+/**
+ * 为字符串存储添加 JSON 序列化，并隔离存储访问和序列化异常。
+ * @param storage 可选的底层存储；未传入时读取为空、写入无操作。
+ * @returns 读取失败时清理对应缓存并返回 `null` 的存储适配器。
+ */
 export const createJsonStorage = (storage?: StateStorage): JsonStorage => {
+  /** 尝试移除指定缓存，忽略底层存储异常以免中断页面渲染。 */
   const removeItem = (key: string) => {
     try {
       storage?.removeItem(key)
@@ -20,6 +26,7 @@ export const createJsonStorage = (storage?: StateStorage): JsonStorage => {
   }
 
   return {
+    /** 解析缓存 JSON；缓存缺失返回 `null`，读取或解析异常时尝试清理缓存。 */
     getItem: <T>(key: string) => {
       try {
         const value = storage?.getItem(key)
@@ -30,6 +37,7 @@ export const createJsonStorage = (storage?: StateStorage): JsonStorage => {
         return null
       }
     },
+    /** 写入序列化后的值；结果为 `undefined` 时删除缓存，异常时忽略此次写入。 */
     setItem: <T>(key: string, value: T) => {
       try {
         const json = JSON.stringify(value)

package/template-vp-monorepo-react-nestjs/packages/i18n/core/src/store.ts

@@ -6,6 +6,7 @@ export interface Store<T extends object> {
   subscribe: (listener: StoreListener) => () => void
 }
 
+/** 比较对象的可枚举字符串键数量与对应值；非对象输入返回 `false`。 */
 export const shallowEqualObject = <T>(a: T, b: T): boolean => {
   if (typeof a !== 'object' || a === null || typeof b !== 'object' || b === null) {
     return false
@@ -20,6 +21,12 @@ export const shallowEqualObject = <T>(a: T, b: T): boolean => {
   return aKeys.every((key) => Object.is(a[key as keyof T], b[key as keyof T]))
 }
 
+/**
+ * 创建可订阅的内存状态容器，仅在浅比较发现变化时通知订阅者。
+ * @param initState 初始状态。
+ * @param onChange 状态提交后、订阅者通知前执行的回调。
+ * @returns 提供状态读取、函数式更新和取消订阅能力的容器。
+ */
 export function createStore<T extends object>(
   initState: T,
   onChange: ({ newState, oldState }: { newState: T; oldState: T }) => void,
@@ -29,6 +36,7 @@ export function createStore<T extends object>(
 
   return {
     getState: () => state,
+    /** 通过更新函数计算新状态，跳过浅相等结果，并同步通知变更。 */
     setState: (updater) => {
       const oldState = state
       const newState = updater(oldState)
@@ -38,6 +46,7 @@ export function createStore<T extends object>(
       onChange({ newState, oldState })
       for (const listener of listeners) listener()
     },
+    /** 注册状态变化监听器，返回移除该监听器的清理函数。 */
     subscribe: (listener) => {
       listeners.add(listener)
       return () => {

package/template-vp-monorepo-react-nestjs/packages/i18n/react/src/index.tsx

@@ -10,6 +10,10 @@ export interface I18nProviderProps {
 
 export const I18nContext = createContext<I18nStore | undefined>(undefined)
 
+/**
+ * 订阅最近的国际化上下文，返回翻译方法、语言切换方法和当前语言。
+ * @throws 未被 `I18nProvider` 包裹时抛出错误。
+ */
 export const useI18n = () => {
   const store = useContext(I18nContext)
   if (!store) throw new Error('useI18n must be used within I18nProvider')
@@ -18,6 +22,7 @@ export const useI18n = () => {
   return { tr, loadLocale, locale }
 }
 
+/** 向子组件提供指定的国际化容器，允许不同子树使用独立的语言状态。 */
 export const I18nProvider = ({ children, store }: I18nProviderProps) => {
   return <I18nContext.Provider value={store}>{children}</I18nContext.Provider>
 }

package/template-vp-monorepo-react-nestjs/packages/i18n/react/src/use-store.ts

@@ -1,14 +1,27 @@
-import { useSyncExternalStore } from 'react'
 import type { I18nState, I18nStore } from '@bubblesjs/i18n-core'
+import { useMemo, useSyncExternalStore } from 'react'
 
+/** 订阅国际化容器，并返回选择器提取的状态。 */
 export function useI18nStore<T>(store: I18nStore, selector: (state: I18nState) => T): T
+/** 订阅国际化容器，并返回完整状态。 */
 export function useI18nStore(store: I18nStore): I18nState
+/** 将外部容器订阅接入 React，根据选择器返回状态片段或完整快照。 */
 export function useI18nStore<T>(
   store: I18nStore,
   selector?: (state: I18nState) => T,
 ): T | I18nState {
-  if (selector) {
-    return useSyncExternalStore(store.subscribe, () => selector(store.getState()))
-  }
-  return useSyncExternalStore(store.subscribe, store.getState)
+  const getSnapshot = useMemo(() => {
+    let cache: { state: I18nState; value: T | I18nState } | undefined
+    return () => {
+      const state = store.getState()
+      if (cache && Object.is(cache.state, state)) {
+        return cache.value
+      }
+      const value = selector ? selector(state) : state
+      cache = { state, value }
+      return value
+    }
+  }, [store, selector])
+
+  return useSyncExternalStore(store.subscribe, getSnapshot)
 }

package/template-vp-monorepo-react-nestjs/packages/i18n/vue/src/index.ts

@@ -30,12 +30,18 @@ export const I18nProvider = defineComponent({
       required: true,
     },
   },
+  /** 为后代组件注入国际化容器，并原样渲染默认插槽。 */
   setup(props, { slots }) {
     provide(I18nKey, props.store)
     return () => slots.default?.()
   },
 })
 
+/**
+ * 订阅注入的国际化容器，提供始终读取最新词条的翻译和语言切换方法。
+ * @returns 翻译方法、异步语言切换方法和响应式语言引用。
+ * @throws 未被 `I18nProvider` 包裹时抛出错误。
+ */
 export function useI18n(): UseI18nReturn {
   const store = inject(I18nKey)
   if (!store) throw new Error('useI18n must be used within I18nProvider')

package/template-vp-monorepo-react-nestjs/packages/i18n/vue/src/use-store.ts

@@ -2,8 +2,11 @@ import { computed, onScopeDispose, shallowRef } from 'vue'
 import type { ComputedRef, ShallowRef } from 'vue'
 import type { I18nState, I18nStore } from '@bubblesjs/i18n-core'
 
+/** 订阅国际化容器，并以计算属性返回选择器提取的状态。 */
 export function useI18nStore<T>(store: I18nStore, selector: (state: I18nState) => T): ComputedRef<T>
+/** 订阅国际化容器，并以浅引用返回完整状态。 */
 export function useI18nStore(store: I18nStore): ShallowRef<I18nState>
+/** 将容器状态接入 Vue 响应系统，并在当前作用域销毁时自动取消订阅。 */
 export function useI18nStore<T>(
   store: I18nStore,
   selector?: (state: I18nState) => T,

package/template-vp-monorepo-react-nestjs/packages/shared/package.json

@@ -30,7 +30,11 @@
   },
   "scripts": {
     "dev": "vp pack --watch",
-    "build": "vp pack"
+    "build": "vp pack",
+    "test": "vp test"
+  },
+  "dependencies": {
+    "zod": "catalog:"
   },
   "devDependencies": {
     "typescript": "catalog:",

package/template-vp-monorepo-react-nestjs/packages/shared/src/index.ts

@@ -1,13 +1,2 @@
-export type {
-  ApiErrorDetail,
-  ApiFailure,
-  AuthUser,
-  CurrentUser,
-  LoginRequest,
-  LoginResult,
-  LogoutResult,
-  RegisterRequest,
-  RegisterResult,
-  SessionTerminalType,
-} from './types'
-export { ACCOUNT_PATTERN, isSessionTerminal, normalizeAccount, SESSION_TERMINALS } from './utils'
+export type * from './types'
+export * from './utils'