Skip to content

Commit a90512d

Browse files
clydinalan-agius4
clydin
authored and
alan-agius4
committed
refactor(@angular/build): cache persistent binary translation buffers in i18n inliner
Persist binary SharedArrayBuffer translation layouts on disk in .angular/cache keyed by translation file integrity hash. The I18nInliner creates a dedicated #translationCache instance under namespace 'translations' alongside #transformedFileCache under namespace 'transforms'. During locale serialization, translationCache.getOrCreate deduplicates in-flight encoding and restores pre-built binary buffers directly from disk, skipping translation dictionary binary encoding on warm builds.
1 parent eacbeb2 commit a90512d

3 files changed

Lines changed: 177 additions & 31 deletions

File tree

‎packages/angular/build/src/builders/application/i18n.ts‎

Lines changed: 5 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -161,19 +161,20 @@ export async function inlineI18n(
161161
if (executionResult.templateUpdates?.size) {
162162
// The development server only allows a single locale but issue a warning if used programmatically (experimental)
163163
// with multiple locales and template HMR.
164-
if (i18nOptions.inlineLocales.size > 1) {
164+
if (localesToInline.length > 1) {
165165
inlineResult.warnings.push(
166166
`Component HMR updates can only be inlined with a single locale. The first locale will be used.`,
167167
);
168168
}
169-
const firstLocale = [...i18nOptions.inlineLocales][0];
169+
const targetLocale = localesToInline[0];
170170

171171
for (const [id, content] of executionResult.templateUpdates) {
172172
const templateUpdateResult = await inliner.inlineTemplateUpdate(
173-
firstLocale,
174-
i18nOptions.locales[firstLocale].translation,
173+
targetLocale.locale,
174+
targetLocale.translation,
175175
content,
176176
id,
177+
targetLocale.translationIntegrity,
177178
);
178179
executionResult.templateUpdates.set(id, templateUpdateResult.code);
179180
inlineResult.errors.push(...templateUpdateResult.errors);

‎packages/angular/build/src/tools/esbuild/i18n-inliner.ts‎

Lines changed: 72 additions & 27 deletions
Original file line numberDiff line numberDiff line change
@@ -36,16 +36,46 @@ const DEFAULT_LOCALE_WINDOW_SIZE = 8;
3636
* SharedArrayBuffer is unavailable.
3737
*
3838
* @param translation The translation messages for a locale, if the locale has any.
39+
* @param translationIntegrity Optional content hash of the translation file for cache lookup.
40+
* @param translationCache Optional Cache instance for binary translation buffers.
3941
* @returns A SharedArrayBuffer or Blob containing the serialized messages, or undefined if none.
4042
*/
41-
function serializeTranslation(
43+
async function serializeTranslation(
4244
translation: Record<string, ɵParsedTranslation> | undefined,
43-
): SharedArrayBuffer | Blob | undefined {
45+
translationIntegrity?: string,
46+
translationCache?: Cache<Uint8Array>,
47+
): Promise<SharedArrayBuffer | Blob | undefined> {
4448
if (!translation) {
4549
return undefined;
4650
}
4751

4852
if (typeof SharedArrayBuffer !== 'undefined') {
53+
if (translationIntegrity && translationCache) {
54+
// Look up or generate binary translation data in the persistent cache.
55+
// A Uint8Array view is stored in the cache store to allow binary persistence.
56+
const binaryData = await translationCache.getOrCreate(translationIntegrity, () => {
57+
return new Uint8Array(encodeTranslationToBuffer(translation));
58+
});
59+
60+
// On a cache miss, getOrCreate returns the newly created Uint8Array backed by the
61+
// original SharedArrayBuffer. Return it directly to avoid an unnecessary allocation and copy.
62+
if (
63+
binaryData.buffer instanceof SharedArrayBuffer &&
64+
binaryData.byteOffset === 0 &&
65+
binaryData.byteLength === binaryData.buffer.byteLength
66+
) {
67+
return binaryData.buffer;
68+
}
69+
70+
// On a warm cache hit, the restored data is backed by a standard ArrayBuffer from disk.
71+
// Copy it into a SharedArrayBuffer so worker threads can access it via zero-copy shared memory.
72+
const buffer = new SharedArrayBuffer(binaryData.byteLength);
73+
new Uint8Array(buffer).set(binaryData);
74+
75+
return buffer;
76+
}
77+
78+
// When persistent caching is not configured, encode directly into a SharedArrayBuffer.
4979
return encodeTranslationToBuffer(translation);
5080
}
5181

@@ -145,7 +175,8 @@ export class I18nInliner {
145175
#cacheInitFailed = false;
146176
#workerPool: WorkerPool;
147177
#cacheStore: PersistentCacheStore | undefined;
148-
#cache: Cache<TransformedFileResult> | undefined;
178+
#transformedFileCache: Cache<TransformedFileResult> | undefined;
179+
#translationCache: Cache<Uint8Array> | undefined;
149180
readonly #localizeFiles: ReadonlyMap<string, BuildOutputFile>;
150181
readonly #unmodifiedFiles: Array<BuildOutputFile>;
151182

@@ -239,6 +270,7 @@ export class I18nInliner {
239270

240271
const fileResultsByLocale = new Map<string, Map<string, TransformedFileResult>>();
241272
for (const { locale } of localeList) {
273+
assert(!fileResultsByLocale.has(locale), 'Duplicate locale provided to inliner: ' + locale);
242274
fileResultsByLocale.set(locale, new Map());
243275
}
244276

@@ -256,23 +288,30 @@ export class I18nInliner {
256288
const localeCacheBases = new Map<string, string>();
257289
const localeBlobs = new Map<string, Blob | SharedArrayBuffer | undefined>();
258290

259-
for (const { locale, translation, translationIntegrity } of windowLocales) {
260-
localeBlobs.set(locale, serializeTranslation(translation));
261-
262-
if (this.#cacheStore) {
263-
localeCacheBases.set(
264-
locale,
265-
calculateHash(
266-
JSON.stringify({
267-
locale,
268-
translation: translationIntegrity || translation,
269-
missingTranslation,
270-
localizeVersion,
271-
}),
272-
),
291+
await Promise.all(
292+
windowLocales.map(async ({ locale, translation, translationIntegrity }) => {
293+
const serialized = await serializeTranslation(
294+
translation,
295+
translationIntegrity,
296+
this.#translationCache,
273297
);
274-
}
275-
}
298+
localeBlobs.set(locale, serialized);
299+
300+
if (this.#cacheStore) {
301+
localeCacheBases.set(
302+
locale,
303+
calculateHash(
304+
JSON.stringify({
305+
locale,
306+
translation: translationIntegrity || translation,
307+
missingTranslation,
308+
localizeVersion,
309+
}),
310+
),
311+
);
312+
}
313+
}),
314+
);
276315

277316
const cacheChecks: CacheCheckItem[] = [];
278317

@@ -284,7 +323,7 @@ export class I18nInliner {
284323
let cacheKey: string | undefined;
285324
let cachedResultPromise: Promise<TransformedFileResult | null> = Promise.resolve(null);
286325

287-
if (this.#cache) {
326+
if (this.#transformedFileCache) {
288327
const fileCacheKeyBase = localeCacheBases.get(locale);
289328
assert(fileCacheKeyBase !== undefined, 'Cache base must exist for locale: ' + locale);
290329

@@ -294,7 +333,7 @@ export class I18nInliner {
294333
hasher.update(fileCacheKeyBase);
295334
cacheKey = hasher.digest();
296335

297-
cachedResultPromise = this.#cache
336+
cachedResultPromise = this.#transformedFileCache
298337
.get(cacheKey)
299338
.then((val) => val ?? null)
300339
.catch(() => null);
@@ -458,8 +497,8 @@ export class I18nInliner {
458497
for (const { locale, cacheKey } of batchEntries) {
459498
fileResultsByLocale.get(locale)?.set(filename, unmodifiedResult);
460499

461-
if (this.#cache && cacheKey) {
462-
cachePromises.push(this.#cache.put(cacheKey, unmodifiedResult));
500+
if (this.#transformedFileCache && cacheKey) {
501+
cachePromises.push(this.#transformedFileCache.put(cacheKey, unmodifiedResult));
463502
}
464503
}
465504
await Promise.allSettled(cachePromises);
@@ -469,9 +508,9 @@ export class I18nInliner {
469508
const matchingEntry = batchEntries.find((e) => e.locale === res.locale);
470509
const cacheKey = matchingEntry?.cacheKey;
471510

472-
if (this.#cache && cacheKey) {
511+
if (this.#transformedFileCache && cacheKey) {
473512
cachePromises.push(
474-
this.#cache.put(cacheKey, {
513+
this.#transformedFileCache.put(cacheKey, {
475514
file: filename,
476515
code: res.code,
477516
map: res.map,
@@ -519,6 +558,7 @@ export class I18nInliner {
519558
translation: Record<string, ɵParsedTranslation> | undefined,
520559
templateCode: string,
521560
templateId: string,
561+
translationIntegrity?: string,
522562
): Promise<{ code: string; errors: string[]; warnings: string[] }> {
523563
const hasLocalize = templateCode.includes(LOCALIZE_KEYWORD);
524564

@@ -535,7 +575,11 @@ export class I18nInliner {
535575
code: templateCode,
536576
filename: templateId,
537577
locale,
538-
translation: serializeTranslation(translation),
578+
translation: await serializeTranslation(
579+
translation,
580+
translationIntegrity,
581+
this.#translationCache,
582+
),
539583
},
540584
{ name: 'inlineCode' },
541585
);
@@ -589,7 +633,8 @@ export class I18nInliner {
589633
createPersistentCacheStore(join(persistentCachePath, 'angular-i18n')),
590634
]);
591635
this.#cacheStore = cacheStore;
592-
this.#cache = cacheStore.createCache('transforms');
636+
this.#transformedFileCache = cacheStore.createCache('transforms');
637+
this.#translationCache = cacheStore.createCache('translations');
593638
} catch {
594639
this.#cacheInitFailed = true;
595640

‎packages/angular/build/src/tools/esbuild/i18n-inliner_spec.ts‎

Lines changed: 100 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -13,6 +13,7 @@ import os from 'node:os';
1313
import path from 'node:path';
1414
import { initializeHash } from '../../utils/hash';
1515
import { type BuildOutputFile, BuildOutputFileType, createOutputFile } from './bundler-files';
16+
import { createPersistentCacheStore } from './cache';
1617
import { I18nInliner } from './i18n-inliner';
1718

1819
/**
@@ -213,6 +214,34 @@ describe('I18nInliner', () => {
213214

214215
expect(code).toBe(source);
215216
});
217+
218+
it('inlines translations with translationIntegrity and persistent caching', async () => {
219+
const cacheDir = await fs.mkdtemp(path.join(os.tmpdir(), 'i18n-template-cache-test-'));
220+
221+
try {
222+
const inliner = new I18nInliner({
223+
missingTranslation: 'error',
224+
outputFiles: [],
225+
persistentCachePath: cacheDir,
226+
});
227+
228+
const translationIntegrity = 'hash-template-integrity-123';
229+
const { code, errors, warnings } = await inliner.inlineTemplateUpdate(
230+
'fr',
231+
{ greeting: translationFor('Bonjour') },
232+
GREETING_SOURCE,
233+
'template-id',
234+
translationIntegrity,
235+
);
236+
237+
expect(errors).toEqual([]);
238+
expect(warnings).toEqual([]);
239+
expect(code).toContain('"Bonjour"');
240+
await inliner.close();
241+
} finally {
242+
await fs.rm(cacheDir, { recursive: true, force: true });
243+
}
244+
});
216245
});
217246

218247
it('safely inlines translations containing special characters, quotes, and newlines', async () => {
@@ -723,4 +752,75 @@ describe('I18nInliner', () => {
723752
await fs.rm(cacheDir, { recursive: true, force: true });
724753
}
725754
});
755+
756+
it('caches binary translation buffer in persistent cache store when translationIntegrity is provided', async () => {
757+
const cacheDir = await fs.mkdtemp(path.join(os.tmpdir(), 'i18n-inliner-trans-cache-test-'));
758+
759+
try {
760+
const inliner1 = new I18nInliner({
761+
missingTranslation: 'error',
762+
outputFiles: [browserFile('main.js', GREETING_SOURCE)],
763+
persistentCachePath: cacheDir,
764+
});
765+
766+
const translationIntegrity = 'hash-test-integrity-12345';
767+
const results1 = await inliner1.inlineAll([
768+
{
769+
locale: 'fr',
770+
translation: { greeting: translationFor('Bonjour') },
771+
translationIntegrity,
772+
},
773+
]);
774+
775+
expect(results1.get('fr')?.errors).toEqual([]);
776+
expect(findFile(results1.get('fr')?.outputFiles ?? [], 'main.js').text).toContain(
777+
'"Bonjour"',
778+
);
779+
await inliner1.close();
780+
781+
// Verify directly that the binary translation buffer was persisted on disk
782+
const store = await createPersistentCacheStore(path.join(cacheDir, 'angular-i18n'));
783+
try {
784+
const translationCache = store.createCache<Uint8Array>('translations');
785+
const cachedData = await translationCache.get(translationIntegrity);
786+
expect(cachedData).toBeInstanceOf(Uint8Array);
787+
expect(cachedData?.byteLength).toBeGreaterThan(0);
788+
} finally {
789+
await store.close();
790+
}
791+
792+
const inliner2 = new I18nInliner({
793+
missingTranslation: 'error',
794+
outputFiles: [browserFile('main.js', GREETING_SOURCE)],
795+
persistentCachePath: cacheDir,
796+
});
797+
798+
const results2 = await inliner2.inlineAll([
799+
{
800+
locale: 'fr',
801+
translation: { greeting: translationFor('Bonjour') },
802+
translationIntegrity,
803+
},
804+
]);
805+
806+
expect(results2.get('fr')?.errors).toEqual([]);
807+
expect(findFile(results2.get('fr')?.outputFiles ?? [], 'main.js').text).toContain(
808+
'"Bonjour"',
809+
);
810+
await inliner2.close();
811+
} finally {
812+
await fs.rm(cacheDir, { recursive: true, force: true });
813+
}
814+
});
815+
816+
it('throws an error when duplicate locales are provided to inlineAll', async () => {
817+
const localeInliner = createInliner([browserFile('main.js', GREETING_SOURCE)]);
818+
819+
await expectAsync(
820+
localeInliner.inlineAll([
821+
{ locale: 'fr', translation: { greeting: translationFor('Bonjour') } },
822+
{ locale: 'fr', translation: { greeting: translationFor('Salut') } },
823+
]),
824+
).toBeRejectedWithError(/Duplicate locale provided to inliner: fr/);
825+
});
726826
});

0 commit comments

Comments
 (0)