import { readdir, readFile } from 'node:fs/promises'; import { join } from 'node:path'; import { analyzeFieldUsageInFile, buildNestedRenameMapFromContent, buildUsageCheckRegex, type CallerDescriptor, getNestedRenameEntryAtPath, INTLAYER_USAGE_REGEX, optimizeSourceFile, type PruneContext, preserveNestedDictionaryFields, SOURCE_FILE_REGEX, } from '@intlayer/babel'; import { requiresDictionaryRegistry } from '@intlayer/config/callers'; import * as ANSIColors from '@intlayer/config/colors'; import { IMPORT_MODE } from '@intlayer/config/defaultValues'; import { colorize, colorizeKey, colorizeNumber, getAppLogger, } from '@intlayer/config/logger'; import { normalizePath } from '@intlayer/config/utils'; import { getNestedDictionaryGraph, getNestedDictionaryReferences, } from '@intlayer/core/dictionaryManipulator'; import { getDictionaries } from '@intlayer/dictionaries-entry'; import { buildComponentFilesList, formatPath, runOnce, } from '@intlayer/engine/utils'; import type { IntlayerConfig } from '@intlayer/types/config'; import type { Dictionary } from '@intlayer/types/dictionary'; import type { PluginOption } from 'vite'; import { intlayerVueAsyncPlugin } from './intlayerVueAsyncPlugin'; // Plugin /** * Returns the Vite plugins responsible for the build optimisation step. * * Contains three internal plugins: * * 1. Vue async plugin – handles Vue SFC async script blocks. * 2. Usage analyser (`vite-intlayer-usage-analyzer`) – pre-scans every * component source file during `buildStart` to build the field-usage map * in `pruneContext`. This runs before any `transform` calls so the * downstream prune plugin always has complete data. * 3. Babel transform (`vite-intlayer-babel-transform`) – rewrites * `useIntlayer('key')` / `getIntlayer('key')` calls into * `useDictionary(_hash)` / `getDictionary(_hash)` and injects the * corresponding JSON (or dynamic `.mjs`) imports. Also applies field-name * renaming when `build.minify` is enabled. * * @param intlayerConfig - Resolved intlayer configuration. * @param pruneContext - Shared mutable state written here and read by the * prune and minify plugins. Pass `null` to skip * analysis (e.g. when both `purge` and `minify` are * disabled). */ export const intlayerOptimize = async ( intlayerConfig: IntlayerConfig, pruneContext: PruneContext | null, compatCallers?: CallerDescriptor[] ): Promise => { try { const logger = getAppLogger(intlayerConfig); const { optimize, purge, minify } = intlayerConfig.build; const editorEnabled = intlayerConfig.editor.enabled; const importMode = intlayerConfig.build.importMode ?? intlayerConfig.dictionary?.importMode; const { dictionariesDir, dynamicDictionariesDir, unmergedDictionariesDir, fetchDictionariesDir, mainDir, baseDir, } = intlayerConfig.system; const dictionariesEntryPath = normalizePath( join(mainDir, 'dictionaries.mjs') ); const unmergedDictionariesEntryPath = normalizePath( join(mainDir, 'unmerged_dictionaries.mjs') ); const dynamicDictionariesEntryPath = normalizePath( join(mainDir, 'dynamic_dictionaries.mjs') ); const componentFilesList = buildComponentFilesList(intlayerConfig).map(normalizePath); const transformableFilesList = [ ...componentFilesList, dictionariesEntryPath, ]; const dictionaries = getDictionaries(intlayerConfig); const dictionaryKeyToImportModeMap: Record< string, 'static' | 'dynamic' | 'fetch' > = {}; (Object.values(dictionaries) as Dictionary[]).forEach((dictionary) => { dictionaryKeyToImportModeMap[dictionary.key] = dictionary.importMode ?? importMode ?? IMPORT_MODE; }); // Dictionaries pulled in by `nest()`: resolved at runtime by `getNesting` // through the dictionary registry, never by a `useIntlayer` call site. const nestedDictionaryReferences = getNestedDictionaryReferences( Object.values(dictionaries) ); // Dictionaries holding `nest()` references: their static import is // re-pointed at the companion module carrying the nest targets. const nestingDictionaryKeys = [ ...getNestedDictionaryGraph(Object.values(dictionaries)).keys(), ]; const isBuildOptimizeEnabled = ( _config: unknown, env: { command: string } ) => { const isBuildCommand = env.command === 'build'; return (optimize === undefined && isBuildCommand) || optimize === true; }; // Field renaming rewrites the content keys the interpreter walks, so the // `keyPath` reported by `ContentSelector` would no longer resolve against // the unmerged dictionaries the visual editor edits. Purging and the // keyPath-neutral part of minification stay active while the editor is on. const isFieldRenameEnabled = !editorEnabled && !!minify; const isAnalysisEnabled = (_config: unknown, env: { command: string }) => (!!purge || !!minify) && isBuildOptimizeEnabled(_config, env); // Compat callers the optimize pass cannot bind (`$_('home.title')`, a // bare `useI18n()`) still read the runtime registry: emptying it would // leave those call sites with no dictionary at all. const keepsDictionaryRegistry = requiresDictionaryRegistry( compatCallers ?? [] ); let partiallyMinifiedDictionariesCount = 0; return [ intlayerVueAsyncPlugin(intlayerConfig, transformableFilesList), // Plugin 1: Usage analyser { name: 'vite-intlayer-usage-analyzer', enforce: 'pre', apply: isAnalysisEnabled, buildStart: async () => { if (!pruneContext) return; const extraCallerNames = (compatCallers ?? []).map( (caller) => caller.callerName ); const usageCheckRegex = buildUsageCheckRegex(extraCallerNames); // Phase 1: Babel-based field-usage analysis for all component files await Promise.all( componentFilesList.map(async (sourceFilePath) => { if (!SOURCE_FILE_REGEX.test(sourceFilePath)) return; let sourceCode: string; try { sourceCode = await readFile(sourceFilePath, 'utf-8'); } catch { return; // unreadable file – skip silently } if (!usageCheckRegex.test(sourceCode)) return; // For Vue/Svelte SFCs, the usage analyzer expects the raw script // content. `analyzeFieldUsageInFile` handles block extraction // internally via `extractScriptBlocks`. try { await analyzeFieldUsageInFile( sourceFilePath, sourceCode, pruneContext, compatCallers ); } catch (parseError) { pruneContext.hasUnparsableSourceFiles = true; logger( [ `Could not parse`, formatPath(sourceFilePath), `for field-usage analysis.`, 'Dictionaries whose usage cannot be confirmed will not be pruned.', parseError instanceof Error ? `(${parseError.message})` : String(parseError), ], { level: 'warn' } ); } }) ); // Phase 2: Framework-specific analysis for Vue / Svelte / Astro SFC // bindings that Babel scope analysis cannot resolve: // Vue → `.value` ref-accessor indirection // Svelte → `$` reactive store prefix // Astro → frontmatter variables referenced in the HTML template if (pruneContext.pendingFrameworkAnalysis.size > 0) { const vuePending = new Map< string, { variableName: string; dictionaryKey: string }[] >(); const sveltePending = new Map< string, { variableName: string; dictionaryKey: string }[] >(); const astroPending = new Map< string, { variableName: string; dictionaryKey: string }[] >(); for (const [ filePath, entries, ] of pruneContext.pendingFrameworkAnalysis) { if (filePath.endsWith('.vue')) { vuePending.set(filePath, entries); } else if (filePath.endsWith('.svelte')) { sveltePending.set(filePath, entries); } else if (filePath.endsWith('.astro')) { astroPending.set(filePath, entries); } } /** Merge framework-extracted field usage into pruneContext. */ const mergeFrameworkResult = ( dictionaryKey: string, fields: Set | undefined ): void => { if (fields && fields.size > 0) { // The Babel rename plugin cannot update source-code property // accesses for SFC indirect patterns → suppress field renaming. pruneContext.dictionariesSkippingFieldRename.add(dictionaryKey); const existing = pruneContext.dictionaryKeyToFieldUsageMap.get(dictionaryKey); if (existing === 'all') return; const merged = existing instanceof Set ? new Set([...existing, ...fields]) : new Set(fields); pruneContext.dictionaryKeyToFieldUsageMap.set( dictionaryKey, merged ); } else { pruneContext.dictionaryKeyToFieldUsageMap.set( dictionaryKey, 'all' ); } }; // Vue files if (vuePending.size > 0) { let extractVueIntlayerFieldUsage: | (( code: string, vars: { variableName: string; dictionaryKey: string }[] ) => Map>) | null = null; try { const vueCompiler = await import('@intlayer/vue-compiler'); extractVueIntlayerFieldUsage = vueCompiler.extractVueIntlayerFieldUsage; } catch { // @intlayer/vue-compiler not installed – fall back to 'all' } for (const [filePath, entries] of vuePending) { if (!extractVueIntlayerFieldUsage) { for (const { dictionaryKey } of entries) { mergeFrameworkResult(dictionaryKey, undefined); } continue; } let fileCode: string; try { fileCode = await readFile(filePath, 'utf-8'); } catch { for (const { dictionaryKey } of entries) { mergeFrameworkResult(dictionaryKey, undefined); } continue; } const result = extractVueIntlayerFieldUsage(fileCode, entries); for (const { dictionaryKey } of entries) { mergeFrameworkResult( dictionaryKey, result.get(dictionaryKey) ); } } } // Svelte files if (sveltePending.size > 0) { let extractSvelteIntlayerFieldUsage: | (( code: string, vars: { variableName: string; dictionaryKey: string }[] ) => Map>) | null = null; try { const svelteCompiler = await import('@intlayer/svelte-compiler'); extractSvelteIntlayerFieldUsage = svelteCompiler.extractSvelteIntlayerFieldUsage; } catch { // @intlayer/svelte-compiler not installed – fall back to 'all' } for (const [filePath, entries] of sveltePending) { if (!extractSvelteIntlayerFieldUsage) { for (const { dictionaryKey } of entries) { mergeFrameworkResult(dictionaryKey, undefined); } continue; } let fileCode: string; try { fileCode = await readFile(filePath, 'utf-8'); } catch { for (const { dictionaryKey } of entries) { mergeFrameworkResult(dictionaryKey, undefined); } continue; } const result = extractSvelteIntlayerFieldUsage( fileCode, entries ); for (const { dictionaryKey } of entries) { mergeFrameworkResult( dictionaryKey, result.get(dictionaryKey) ); } } } // Astro files // Frontmatter variables are used in the HTML template, which is not // visible to Babel's scope analysis. Scan the template section for // `variableName.fieldName` accesses using a lightweight regex pass. if (astroPending.size > 0) { for (const [filePath, entries] of astroPending) { let fileCode: string; try { fileCode = await readFile(filePath, 'utf-8'); } catch { for (const { dictionaryKey } of entries) { mergeFrameworkResult(dictionaryKey, undefined); } continue; } // Extract only the template (everything after the closing ---). // The frontmatter was already handled by Babel in Phase 1. const fenceMatch = /^---\r?\n[\s\S]*?\r?\n---/.exec(fileCode); const template = fenceMatch ? fileCode.slice(fenceMatch.index + fenceMatch[0].length) : fileCode; for (const { variableName, dictionaryKey } of entries) { const escapedVar = variableName.replace( /[.*+?^${}()|[\]\\]/g, '\\$&' ); const fieldRe = new RegExp( `\\b${escapedVar}\\.([a-zA-Z_$][a-zA-Z0-9_$]*)`, 'g' ); const foundFields = new Set(); let m = fieldRe.exec(template); while (m !== null) { foundFields.add(m[1]!); m = fieldRe.exec(template); } mergeFrameworkResult( dictionaryKey, foundFields.size > 0 ? foundFields : undefined ); } } } } // Phase 2.5: Keep `nest()` targets resolvable — must run before the // rename maps of Phase 4 are built. preserveNestedDictionaryFields( pruneContext, nestedDictionaryReferences ); // Phase 3: Warn about untracked bindings (plain variable assignments) for (const [ dictionaryKey, sourceFilePaths, ] of pruneContext.dictionaryKeysWithUntrackedBindings) { logger( [ `Dictionary`, colorizeKey(dictionaryKey), `cannot be purged or minified.`, `\n Reason: the result of`, `${colorize(`useIntlayer(`, ANSIColors.GREY_LIGHT)}${colorizeKey( `'${dictionaryKey}'` )}${colorize(`)`, ANSIColors.GREY_LIGHT)}`, `is assigned to a plain variable in:`, ...sourceFilePaths.map( (filePath) => `\n - ${formatPath(filePath)}` ), ], { level: 'warn' } ); } // Phase 4: Build field-rename map for minification // Reads each compiled dictionary JSON to discover the full nested // user-defined field structure, then builds a NestedRenameMap that // assigns short alphabetic aliases at every level. if (isFieldRenameEnabled) { for (const [ dictionaryKey, fieldUsage, ] of pruneContext.dictionaryKeyToFieldUsageMap) { if (fieldUsage === 'all') continue; // Fetch-mode dictionaries are served from a remote API using // original field names – renaming would break the client/server // contract. if (dictionaryKeyToImportModeMap[dictionaryKey] === 'fetch') continue; // SFC indirect access: skip field rename for these dictionaries // to avoid a JSON ↔ source mismatch at runtime. if ( pruneContext.dictionariesSkippingFieldRename.has(dictionaryKey) ) continue; // Read dictionary content (static JSON first, then dynamic per-locale) let dictionaryContent: unknown = null; const staticJsonPath = join( dictionariesDir, `${dictionaryKey}.json` ); try { const raw = await readFile(staticJsonPath, 'utf-8'); const parsed = JSON.parse(raw) as Record; dictionaryContent = parsed.content; } catch { try { const dynamicDir = join( dynamicDictionariesDir, dictionaryKey ); const localeFiles = await readdir(dynamicDir); const firstJsonFile = localeFiles.find((f) => f.endsWith('.json') ); if (firstJsonFile) { const raw = await readFile( join(dynamicDir, firstJsonFile), 'utf-8' ); const parsed = JSON.parse(raw) as Record; dictionaryContent = parsed.content; } } catch { // Dictionary file not readable – skip rename for this key } } if (!dictionaryContent) continue; // Build the rename map from ALL user-defined fields in the // dictionary — not just the ones statically consumed by source // files. Using the full set ensures that: // 1. Every field in the compiled JSON is renamed (even if // pruned-out fields still appear when purge is disabled). // 2. The short-name assignment is stable: the alphabetical // order of all fields determines each short name, so adding // or removing a consumer never changes names for others. // 3. There is no source ↔ JSON mismatch: both sides use the // identical map regardless of which subset is consumed. const nestedRenameMap = buildNestedRenameMapFromContent(dictionaryContent); // Skip renaming below opaque values that have nested // user-defined structure – renaming those sub-keys would // silently break child components that consume the value as-is. const opaqueFieldMap = pruneContext.dictionaryKeysWithOpaqueFields.get(dictionaryKey); if (opaqueFieldMap) { const dangerousOccurrences = [ ...opaqueFieldMap.values(), ].filter( (occurrence) => (getNestedRenameEntryAtPath( nestedRenameMap, occurrence.fieldPath )?.children.size ?? 0) > 0 ); if (dangerousOccurrences.length > 0) { partiallyMinifiedDictionariesCount += 1; logger( [ `Dictionary`, colorizeKey(dictionaryKey), `partially minified.`, ...dangerousOccurrences.flatMap((occurrence) => [ `\n Opaque field:`, colorize( `'${occurrence.fieldPath.join('.')}'`, ANSIColors.BLUE ), `(nested keys preserved for stability).`, ...occurrence.locations.map( (loc) => `\n at ${formatPath(loc)}` ), ]), ], { level: 'warn', isVerbose: true } ); // Disable renaming for the children of opaque values to // prevent breaking components that receive the value as a // prop. for (const occurrence of dangerousOccurrences) { const entry = getNestedRenameEntryAtPath( nestedRenameMap, occurrence.fieldPath ); if (entry) { entry.children = new Map(); } } } } if (nestedRenameMap.size > 0) { pruneContext.dictionaryKeyToFieldRenameMap.set( dictionaryKey, nestedRenameMap ); } } if (partiallyMinifiedDictionariesCount > 0) { runOnce( join( baseDir, '.intlayer', 'cache', 'intlayer-partial-minify-summary.lock' ), () => { logger([ `Partially minified`, colorizeNumber(partiallyMinifiedDictionariesCount), `dictionar${partiallyMinifiedDictionariesCount === 1 ? 'y' : 'ies'}`, `(preserved nested keys for opaque fields).`, ]); }, { cacheTimeoutMs: 1000 * 5 } ); } } }, }, // Plugin 2: Babel transform { name: 'vite-intlayer-babel-transform', enforce: 'post', // Run after framework transformations (e.g. Vue SFC) apply: (_config, env) => { const isBuildCommand = env.command === 'build'; const isEnabled = (optimize === undefined && isBuildCommand) || optimize === true; if (!isBuildCommand || !isEnabled) return false; runOnce( join( baseDir, '.intlayer', 'cache', 'intlayer-optimize-plugin-enabled.lock' ), () => { logger([ `Build optimization ${colorize('enabled', ANSIColors.GREEN)}`, colorize('(import mode:', ANSIColors.GREY_DARK), colorize(importMode ?? IMPORT_MODE, ANSIColors.BLUE), colorize(')', ANSIColors.GREY_DARK), ]); // The minify plugin reports the field-rename step standing down // when the editor is enabled, so this line stays a plain one. if (minify) { logger( `Dictionary minification ${colorize('enabled', ANSIColors.GREEN)}` ); } if (purge) { logger( `Dictionary purge unused keys ${colorize('enabled', ANSIColors.GREEN)}` ); } }, { cacheTimeoutMs: 1000 * 10 } ); return true; }, transform: async (sourceCode, moduleId, options) => { // Strip query parameters added by Vue/Svelte loaders // e.g. "HelloWorld.vue?vue&type=script&setup=true&lang.ts" → "HelloWorld.vue" const sourceFilePath = normalizePath( moduleId.split('?', 1)[0] ?? moduleId ); if (!SOURCE_FILE_REGEX.test(sourceFilePath)) return null; if (!transformableFilesList.includes(sourceFilePath)) return null; const isDictionaryEntryFile = sourceFilePath === dictionariesEntryPath; // Match native intlayer calls plus any configured compat callers // (`useTranslation`, `useTranslations`, …) so compat-only files are // still optimized. const optimizeUsageRegex = compatCallers?.length ? buildUsageCheckRegex( compatCallers.map((caller) => caller.callerName) ) : INTLAYER_USAGE_REGEX; const isUsingIntlayer = optimizeUsageRegex.test(sourceCode); if (!isUsingIntlayer && !isDictionaryEntryFile) return null; // Field rename + optimize (useIntlayer('key') → useDictionary(_hash)) // in a single Babel pass: the rename runs first, before the optimize // step erases the dictionary key it keys off. const fieldRenamePruneContext = isFieldRenameEnabled && pruneContext && isUsingIntlayer ? pruneContext : undefined; const transformResult = await optimizeSourceFile( sourceCode, sourceFilePath, { optimize, dictionariesDir, dictionariesEntryPath, unmergedDictionariesEntryPath, unmergedDictionariesDir, dynamicDictionariesDir, dynamicDictionariesEntryPath, fetchDictionariesDir, fetchDictionariesEntryPath: join( mainDir, 'fetch_dictionaries.mjs' ), importMode, filesList: transformableFilesList, replaceDictionaryEntry: isBuildOptimizeEnabled(null, { command: 'build' }) && !keepsDictionaryRegistry, nestingDictionaryKeys, dictionaryModeMap: dictionaryKeyToImportModeMap, isServer: options?.ssr === true, compatCallers, }, fieldRenamePruneContext ); if (!transformResult) return null; return { code: transformResult.code, map: transformResult.map as any, }; }, }, ]; } catch (pluginInitError) { console.warn( '[vite-intlayer] Failed to initialise optimization plugin:', pluginInitError ); return []; } };