Skip to content

armgit / dify

Public Imported from GitHub
0

Build Agentic workflows, RAG pipelines, with rich AI model and tool support on one collaborative workspace. Deploy on cloud, VPC, or self-hosted, so teams move from prototype to production without rebuilding the stack.

perf(web): streamline vinext i18n build analysis (#42902)

Stephen Zhoubba6aad65240
diff --git a/web/plugins/vite/__tests__/i18n-analysis.spec.ts b/web/plugins/vite/__tests__/i18n-analysis.spec.ts
index 6e50837ecc9..34e511d3de4 100644
--- a/web/plugins/vite/__tests__/i18n-analysis.spec.ts
+++ b/web/plugins/vite/__tests__/i18n-analysis.spec.ts
@@ -189,6 +189,11 @@ describe('i18n build check', () => {
expect(readFileSync(localeFile, 'utf8')).toBe(content)
})
+ it('propagates analysis worker failures to the build', async () => {
+ writeFileSync(localeFile, '[]')
+ await expect(buildFixture()).rejects.toThrow('Invalid translation catalog: app.json')
+ })
+
it('allows builds after unused translations are removed', async () => {
writeFileSync(localeFile, JSON.stringify({ used: 'Used' }))
@@ -290,6 +295,66 @@ describe('i18n build check', () => {
},
)
+ it('does not resolve translation imports from discarded RSC reference scans', async () => {
+ writeFileSync(localeFile, JSON.stringify({ used: 'Used' }))
+ writeFileSync(
+ path.join(root, 'selector.ts'),
+ 'export const selector = ($: Record<string, string>) => $.used',
+ )
+ writeFileSync(
+ path.join(root, 'entry.ts'),
+ `import { selector } from './selector'
+ export function label(t: (selector: (source: Record<string, string>) => string) => string) {
+ return t(selector)
+ }`,
+ )
+ const manager = { isScanBuild: false }
+ let scanFinished = false
+ const reports: AnalysisReport[] = []
+ const builder = await createBuilder({
+ root,
+ configFile: false,
+ logLevel: 'silent',
+ plugins: [
+ {
+ // Model the RSC plugin's public scan flag and build ordering.
+ name: 'rsc:minimal',
+ api: { manager },
+ enforce: 'pre',
+ buildStart() {
+ scanFinished = false
+ },
+ buildEnd() {
+ scanFinished = manager.isScanBuild
+ },
+ resolveId(id) {
+ if (id === './selector' && scanFinished)
+ throw new Error('Discarded scan imports must not be resolved again')
+ },
+ },
+ i18nAnalysisPlugin({ onAnalysis: (report) => reports.push(report) }),
+ ],
+ builder: {
+ async buildApp(builder) {
+ manager.isScanBuild = true
+ await builder.build(builder.environments.client!)
+ manager.isScanBuild = false
+ await builder.build(builder.environments.client!)
+ },
+ },
+ build: {
+ write: false,
+ lib: { entry: path.join(root, 'entry.ts'), formats: ['es'] },
+ },
+ })
+
+ await expect(builder.buildApp()).resolves.toBeUndefined()
+ expect(reports).toHaveLength(1)
+ expect(reports[0]!.evidence).toContainEqual(
+ expect.objectContaining({ kind: 'usage', message: 'Static key: used' }),
+ )
+ })
+
it('retains usages from environment-specific versions of the same module', async () => {
writeFileSync(localeFile, JSON.stringify({ client: 'Client', ssr: 'SSR' }))
const builder = await createBuilder({
diff --git a/web/plugins/vite/__tests__/i18n-graph.spec.ts b/web/plugins/vite/__tests__/i18n-graph.spec.ts
index 51270f72540..316c0be0d7a 100644
--- a/web/plugins/vite/__tests__/i18n-graph.spec.ts
+++ b/web/plugins/vite/__tests__/i18n-graph.spec.ts
@@ -410,6 +410,66 @@ describe('translation graph analysis', () => {
})
})
+ it('uses the selected overload namespace instead of the first declaration', () => {
+ writeJson('i18n/locales/en-US/app.json', { title: 'App', unused: 'Unused' })
+ writeJson('i18n/locales/en-US/login.json', { title: 'Login', unused: 'Unused' })
+ writeSource(
+ 'src/overloaded.ts',
+ `
+ type SelectorParam<T> = (source: Record<string, string>) => string
+ declare function metadata(namespace: 'app', selector: SelectorParam<'app'>): string
+ declare function metadata(namespace: 'login', selector: SelectorParam<'login'>): string
+ export const title = metadata('login', $ => $.title)
+ `,
+ )
+
+ expect(checkTranslationGraph(webRoot, modules).unused).toEqual({
+ app: ['title', 'unused'],
+ login: ['unused'],
+ })
+ })
+
+ it('retains selector types inferred through an unconstrained generic parameter', () => {
+ writeJson('i18n/locales/en-US/app.json', { title: 'App', unused: 'Unused' })
+ writeJson('i18n/locales/en-US/login.json', { title: 'Login', unused: 'Unused' })
+ writeSource(
+ 'src/inferred.ts',
+ `
+ type SelectorParam<T> = (source: Record<string, string>) => string
+ declare function invoke<T>(selector: T): string
+ const selector: SelectorParam<'login'> = $ => $.title
+ export const title = invoke(selector)
+ `,
+ )
+
+ expect(checkTranslationGraph(webRoot, modules).unused).toEqual({
+ app: ['title', 'unused'],
+ login: ['unused'],
+ })
+ })
+
+ it.each([
+ ['conditional', "T extends 'login' ? SelectorParam<'login'> : SelectorParam<'app'>"],
+ ['indexed access', 'Selectors[T]'],
+ ])('retains selectors resolved through a generic %s type', (_, parameterType) => {
+ writeJson('i18n/locales/en-US/app.json', { title: 'App', unused: 'Unused' })
+ writeJson('i18n/locales/en-US/login.json', { title: 'Login', unused: 'Unused' })
+ writeSource(
+ 'src/deferred-selector.ts',
+ `
+ type SelectorParam<T> = (source: Record<string, string>) => string
+ type Selectors = { app: SelectorParam<'app'>; login: SelectorParam<'login'> }
+ declare function invoke<T extends keyof Selectors>(namespace: T, selector: ${parameterType}): string
+ export const title = invoke('login', $ => $.title)
+ `,
+ )
+
+ expect(checkTranslationGraph(webRoot, modules).unused).toEqual({
+ app: ['title', 'unused'],
+ login: ['unused'],
+ })
+ })
+
it('keeps possible matches across namespaces when a selector namespace cannot be resolved', () => {
writeJson('i18n/locales/en-US/app.json', { title: 'App', unused: 'Unused' })
writeJson('i18n/locales/en-US/login.json', { title: 'Login', unused: 'Unused' })
diff --git a/web/plugins/vite/i18n-analysis.ts b/web/plugins/vite/i18n-analysis.ts
index c08d16f8fea..b04d471bd73 100644
--- a/web/plugins/vite/i18n-analysis.ts
+++ b/web/plugins/vite/i18n-analysis.ts
@@ -1,6 +1,7 @@
+import type { PluginApi } from '@vitejs/plugin-rsc'
import type { Logger, Plugin } from 'vite'
import type { TranslationAdapter } from './i18n-analysis/api'
-import type { ModuleResolutions } from './i18n-analysis/compiler'
+import type { createImportBindingReader, ModuleResolutions } from './i18n-analysis/compiler'
import type { AnalysisEvidence } from './i18n-analysis/graph'
import type {
EnvironmentUsage,
@@ -13,6 +14,7 @@ import fs from 'node:fs/promises'
import path from 'node:path'
import { normalizePath } from 'vite'
import { analyzeEnvironmentRoutes, validateRouteNamespaces } from './i18n-analysis/routes'
+import { analyzeGraphInWorker } from './i18n-analysis/worker'
const SOURCE_META = 'dify:i18n-source'
@@ -51,6 +53,8 @@ export function i18nAnalysisPlugin(
let logger: Logger
let reportPath: string | undefined
let buildingApp = false
+ let rscApi: PluginApi | undefined
+ let readBindings: ReturnType<typeof createImportBindingReader> | undefined
const graphs = new Map<
string,
{
@@ -65,24 +69,33 @@ export function i18nAnalysisPlugin(
const moduleId = normalizePath
const checks = new Map<string, Promise<void>>()
const snapshots = new Map<string, string>()
+ const environmentOrder = new Set<string>()
const check = async () => {
+ // Import collection is complete; do not retain source strings and binding
+ // arrays while the TypeScript programs allocate their type state.
+ readBindings = undefined
const started = performance.now()
- const { checkTranslationGraph, createAnalysisContext } = await import('./i18n-analysis/graph')
- const context = createAnalysisContext(root, options.adapters)
- const setupMs = performance.now() - started
const environments = new Map<string, EnvironmentUsage>()
const evidence: AnalysisReport['evidence'] = []
const metrics: AnalysisReport['metrics'] = {
totalMs: 0,
- setupMs,
+ setupMs: 0,
routesMs: 0,
environments: [],
}
let unused: Record<string, string[]> | undefined
const protectedNamespaces = new Set<string>()
- for (const [environment, graph] of graphs) {
- const result = checkTranslationGraph(root, graph.modules, graph.resolutions, context)
+ for (const environment of environmentOrder) {
+ const graph = graphs.get(environment)
+ if (!graph) continue
+ const result = await analyzeGraphInWorker({
+ root,
+ modules: graph.modules,
+ resolutions: graph.resolutions,
+ adapters: options.adapters ?? [],
+ })
+ metrics.setupMs += result.setupMs
environments.set(environment, {
dependencies: graph.dependencies,
usage: result.moduleNamespaces,
@@ -180,7 +193,9 @@ export function i18nAnalysisPlugin(
apply: 'build',
enforce: 'pre',
sharedDuringBuild: true,
- configResolved(config) {
+ async configResolved(config) {
+ const { getPluginApi } = await import('@vitejs/plugin-rsc')
+ rscApi = getPluginApi(config)
root = config.root
logger = config.logger
reportPath = config.build.write
@@ -188,19 +203,24 @@ export function i18nAnalysisPlugin(
: undefined
},
async buildApp() {
+ readBindings = undefined
graphs.clear()
+ environmentOrder.clear()
checks.clear()
snapshots.clear()
buildingApp = true
},
buildStart() {
if (this.meta.watchMode) {
+ readBindings = undefined
checks.delete(this.environment.name)
snapshots.delete(this.environment.name)
}
if (!buildingApp && !snapshots.has(this.environment.name)) {
graphs.clear()
+ environmentOrder.clear()
}
+ environmentOrder.add(this.environment.name)
},
transform: {
filter: {
@@ -214,6 +234,9 @@ export function i18nAnalysisPlugin(
},
async buildEnd(error) {
if (error) return
+ // RSC explicitly marks its reference scans; write:false alone also
+ // describes ordinary in-memory builds whose usage must be checked.
+ if (buildingApp && rscApi?.manager.isScanBuild) return
const resolutionStarted = performance.now()
const graph = new Map<string, string>()
const compiledModules = new Map<string, string>()
@@ -259,8 +282,9 @@ export function i18nAnalysisPlugin(
if (snapshots.get(this.environment.name) === snapshot) return
checks.delete(this.environment.name)
snapshots.set(this.environment.name, snapshot)
- const { hasClientDirective, resolveTranslationImports } =
+ const { createImportBindingReader, hasClientDirective, resolveTranslationImports } =
await import('./i18n-analysis/compiler')
+ readBindings ??= createImportBindingReader()
const clientReferences = new Set<string>()
if (this.environment.name === 'rsc') {
for (const [id, code] of graph) {
@@ -280,6 +304,7 @@ export function i18nAnalysisPlugin(
},
(specifier) =>
!specifier.includes('?') && this.environment.config.assetsInclude(specifier),
+ readBindings,
)
graphs.set(this.environment.name, {
modules: graph,
@@ -291,6 +316,7 @@ export function i18nAnalysisPlugin(
})
},
closeBundle() {
+ if (!buildingApp) readBindings = undefined
snapshots.delete(this.environment.name)
checks.delete(this.environment.name)
},
@@ -321,6 +347,7 @@ export function i18nAnalysisPlugin(
await check()
} finally {
buildingApp = false
+ readBindings = undefined
graphs.clear()
}
},
diff --git a/web/plugins/vite/i18n-analysis/README.md b/web/plugins/vite/i18n-analysis/README.md
index dec09f371c4..4c2fff2e09b 100644
--- a/web/plugins/vite/i18n-analysis/README.md
+++ b/web/plugins/vite/i18n-analysis/README.md
@@ -3,6 +3,8 @@
`i18nAnalysisPlugin()` prints a compact summary during production Vite builds,
before the existing unused-key check. With Vinext it reports once, after combining
the completed client, SSR and RSC graphs. Development does not run the analysis.
+Reference scans explicitly marked by the RSC plugin API are skipped; ordinary
+`build.write: false` builds still receive the full analysis.
The console shows route and diagnostic counts, namespaces protected by dynamic
keys, and the report path. Diagnostic counts include separate environment records.
@@ -158,14 +160,33 @@ An empty unresolved-import list does not imply complete dependency coverage.
A dynamic key can protect an entire namespace; these records explain which calls
prevent an unused-key conclusion.
-`metrics` records shared setup, per-environment resolution, Program/checker setup,
+`metrics` records combined environment setup, per-environment resolution, Program/checker setup,
semantic analysis and route traversal durations, plus module and resolver-call
counts. `totalMs` sums work for the final environment graphs and final analysis;
it excludes superseded scan graphs, output serialization and the rest of the build,
and is not wall-clock build duration when environments run concurrently.
+Call-signature resolution is limited to overloaded or generic calls whose
+parameters can expose a `SelectorParam` type. Ordinary object/function parameter
+shapes do not require argument inference; deferred types (including type parameters,
+conditional, indexed-access, union/intersection and mapped types) retain resolution.
+Calls without arguments skip translation-function inference while explicit namespace
+loading and traversal of their children remain unchanged.
+
+Each environment's semantic analysis runs in a separate Node worker. Environments
+run sequentially, and analysis waits for the worker to exit before starting the next
+one, releasing its TypeScript Program and type state. Only plain analysis results
+return to the build process; errors still fail the build. Worker startup and message
+transfer are included in `totalMs`. This uses the repository's Node 24 TypeScript
+support, so the worker's local imports have explicit `.ts` extensions.
+
Catalog, exact-key/plural indexes, wildcard matches and compiler options are shared
-within one analysis. Runtime template prefixes are retained even when an assertion
+within each environment analysis. Import binding syntax is cached by complete source text within
+one build, including across environments. Only plain binding data is cached, not
+TypeScript ASTs, resolved targets or type state. Environment resolution stays independent,
+and the syntax cache is discarded before semantic analysis, when the build ends,
+or when a watch rebuild starts.
+Runtime template prefixes are retained even when an assertion
widens the key to every property of a JSON catalog. Identical multi-format builds in the same open bundle reuse
analysis; changes to source, transformed code or graph edges invalidate that reuse.
Closing the bundle or starting a watch rebuild clears it. Programs and type state
diff --git a/web/plugins/vite/i18n-analysis/compiler.ts b/web/plugins/vite/i18n-analysis/compiler.ts
index b53c0ae26f0..164079ffc98 100644
--- a/web/plugins/vite/i18n-analysis/compiler.ts
+++ b/web/plugins/vite/i18n-analysis/compiler.ts
@@ -120,6 +120,18 @@ function importBindings(code: string): ImportBinding[] {
return result
}
+export function createImportBindingReader() {
+ const cache = new Map<string, readonly ImportBinding[]>()
+ return (code: string) => {
+ let bindings = cache.get(code)
+ if (!bindings) {
+ bindings = importBindings(code)
+ cache.set(code, bindings)
+ }
+ return bindings
+ }
+}
+
export function hasClientDirective(code: string) {
if (!code.includes('use client')) return false
const source = ts.createSourceFile(
@@ -144,6 +156,7 @@ export async function resolveTranslationImports(
importer: string,
) => Promise<{ id: string; external?: boolean } | undefined>,
isAsset: (specifier: string) => boolean = () => false,
+ readBindings = createImportBindingReader(),
) {
const resolutions = new Map<string, Map<string, ModuleResolution>>()
let resolveCalls = 0
@@ -187,8 +200,8 @@ export async function resolveTranslationImports(
else if (!declarationImports.has(specifier) && !isAsset(specifier))
imports.set(specifier, null)
}
- const before = importBindings(source)
- const after = importBindings(code)
+ const before = readBindings(source)
+ const after = readBindings(code)
const proposals = new Map<string, Set<string | null | undefined>>()
const record = (specifier: string, target: string | null | undefined) => {
const values = proposals.get(specifier) ?? new Set<string | null | undefined>()
diff --git a/web/plugins/vite/i18n-analysis/graph-worker.ts b/web/plugins/vite/i18n-analysis/graph-worker.ts
new file mode 100644
index 00000000000..1bec24d9fba
--- /dev/null
+++ b/web/plugins/vite/i18n-analysis/graph-worker.ts
@@ -0,0 +1,23 @@
+import type { TranslationAdapter } from './api.ts'
+import type { ModuleResolutions } from './compiler.ts'
+import { parentPort, workerData } from 'node:worker_threads'
+import { checkTranslationGraph, createAnalysisContext } from './graph.ts'
+
+export type GraphWorkerInput = {
+ root: string
+ modules: ReadonlyMap<string, string>
+ resolutions: ModuleResolutions
+ adapters: readonly TranslationAdapter[]
+}
+
+export type GraphWorkerResult = ReturnType<typeof checkTranslationGraph> & { setupMs: number }
+
+const { root, modules, resolutions, adapters } = workerData as GraphWorkerInput
+const started = performance.now()
+const context = createAnalysisContext(root, adapters)
+const setupMs = performance.now() - started
+const result: GraphWorkerResult = {
+ ...checkTranslationGraph(root, modules, resolutions, context),
+ setupMs,
+}
+parentPort!.postMessage(result)
diff --git a/web/plugins/vite/i18n-analysis/graph.ts b/web/plugins/vite/i18n-analysis/graph.ts
index 0fb61d0a464..3a8fe91a164 100644
--- a/web/plugins/vite/i18n-analysis/graph.ts
+++ b/web/plugins/vite/i18n-analysis/graph.ts
@@ -1,10 +1,10 @@
-import type { TranslationAdapter } from './api'
-import type { ModuleResolutions } from './compiler'
+import type { TranslationAdapter } from './api.ts'
+import type { ModuleResolutions } from './compiler.ts'
import path from 'node:path'
import * as ts from 'typescript'
-import { createTranslationApiResolver } from './api'
-import { camelCase, readTranslationCatalog } from './catalog'
-import { createTranslationProgram, readCompilerOptions } from './compiler'
+import { createTranslationApiResolver } from './api.ts'
+import { camelCase, readTranslationCatalog } from './catalog.ts'
+import { createTranslationProgram, readCompilerOptions } from './compiler.ts'
const MAX_VALUES = 200
const escapeRegex = (text: string) => text.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')
@@ -85,6 +85,7 @@ export function checkTranslationGraph(
context = createAnalysisContext(root),
) {
const { catalog } = context.translations
+ const literalKeys = new Set([...catalog.values()].flatMap((keys) => [...keys]))
const programStarted = performance.now()
const { program, fileNames } = createTranslationProgram(
root,
@@ -229,6 +230,27 @@ export function checkTranslationGraph(
return constraint && constraint !== type ? selectorType(constraint) : undefined
}
+ function mayInstantiateSelector(type: ts.Type): boolean {
+ if (selectorType(type)) return true
+ // Instantiation can reduce these types to a selector alias. Keep them even
+ // when the declaration itself does not expose SelectorParam.
+ if (
+ type.flags &
+ (ts.TypeFlags.TypeParameter |
+ ts.TypeFlags.IndexedAccess |
+ ts.TypeFlags.Conditional |
+ ts.TypeFlags.Substitution |
+ ts.TypeFlags.UnionOrIntersection)
+ )
+ return true
+ // Ordinary object/function types retain their shape and alias when their
+ // type arguments are instantiated. Mapped types can instead reduce.
+ return !!(
+ type.flags & ts.TypeFlags.Object &&
+ (type as ts.ObjectType).objectFlags & (ts.ObjectFlags.Mapped | ts.ObjectFlags.ReverseMapped)
+ )
+ }
+
function typedTranslation(node: ts.Node, call?: ts.CallExpression): Translation | undefined {
const type = checker.getTypeAtLocation(node)
const brand = type.getProperty('$TFunctionBrand')
@@ -238,8 +260,21 @@ export function checkTranslationGraph(
}
// Prefer the instantiated namespace. Inferred selector functions can lose
// their alias, so retain declaration signatures for recognizing adapters.
- const resolved = call && checker.getResolvedSignature(call)
- const signatures = [...(resolved ? [resolved] : []), ...type.getCallSignatures()]
+ const declared = type.getCallSignatures()
+ // Resolving a call checks its arguments and contextual types too. Only
+ // request that work if overload selection or generic instantiation could
+ // expose a selector parameter; unrelated generic APIs need neither.
+ const resolved =
+ call &&
+ (declared.length > 1 || declared.some((signature) => signature.typeParameters?.length)) &&
+ declared.some((signature) =>
+ signature.parameters.some((parameter) =>
+ mayInstantiateSelector(checker.getTypeOfSymbolAtLocation(parameter, node)),
+ ),
+ )
+ ? checker.getResolvedSignature(call)
+ : undefined
+ const signatures = [...(resolved ? [resolved] : []), ...declared]
for (const signature of signatures) {
for (const [argument, parameter] of signature.parameters.entries()) {
const selector = selectorType(checker.getTypeOfSymbolAtLocation(parameter, node))
@@ -539,7 +574,13 @@ export function checkTranslationGraph(
function visit(node: ts.Node) {
if (isAdapter(node)) return
currentSite = node
- if (ts.isStringLiteralLike(node) && (node.text.includes('.') || node.text.includes(':'))) {
+ // Contextual key unions can only contribute usage when the literal itself
+ // exists in a catalog. Avoid type-checking unrelated paths, URLs and text.
+ if (
+ ts.isStringLiteralLike(node) &&
+ (node.text.includes('.') || node.text.includes(':')) &&
+ literalKeys.has(node.text)
+ ) {
const contextual = checker.getContextualType(node)
const values = contextual && literalTypes(contextual)
if (values?.includes(node.text)) {
@@ -573,7 +614,9 @@ export function checkTranslationGraph(
prefix: '',
argument: api.selectorArgument,
}
- : translation(node.expression, node)
+ : node.arguments.length
+ ? translation(node.expression, node)
+ : undefined
const argument = info && node.arguments[info.argument]
if (info && argument) {
const options =
diff --git a/web/plugins/vite/i18n-analysis/worker.ts b/web/plugins/vite/i18n-analysis/worker.ts
new file mode 100644
index 00000000000..bc64a30c4db
--- /dev/null
+++ b/web/plugins/vite/i18n-analysis/worker.ts
@@ -0,0 +1,19 @@
+import type { GraphWorkerInput, GraphWorkerResult } from './graph-worker.ts'
+import { Worker } from 'node:worker_threads'
+
+export function analyzeGraphInWorker(input: GraphWorkerInput): Promise<GraphWorkerResult> {
+ return new Promise((resolve, reject) => {
+ const worker = new Worker(new URL('./graph-worker.ts', import.meta.url), { workerData: input })
+ let result: GraphWorkerResult | undefined
+ worker.once('message', (message: GraphWorkerResult) => {
+ result = message
+ })
+ worker.once('error', reject)
+ worker.once('exit', (code) => {
+ // Wait for the isolate to exit, not just its message, so its TypeScript
+ // program and type state are released before the next environment starts.
+ if (code === 0 && result) resolve(result)
+ else reject(new Error(`i18n graph analysis worker exited without a result (code ${code})`))
+ })
+ })
+}