feat: add setCompiledTranslation bypass method (#1605)

Adds TranslateService.setCompiledTranslation(lang, translations, shouldMerge?)
which stores already-compiled translations directly via the store, bypassing
the configured TranslateCompiler. Use this when translations are already in
their final, interpolator-ready form (e.g. interpolation functions produced
at build time). For raw translations that still need compilation, continue
using setTranslation.

Fixes a v17 regression where passing function-valued objects to setTranslation
no longer typechecked. The v17 raw-vs-compiled type split (TranslationObject
vs InterpolatableTranslationObject) is preserved — this is the missing public
entry point for the compiled side, not a change to the type hierarchy.

Zero breaking changes. No existing signatures, type definitions, or internal
behavior modified. setTranslation is unchanged and still runs the compiler;
the new method delegates directly to TranslateStore.setTranslations.

Bidirectional JSDoc cross-references link the two methods so users hitting
the #1605 type error in setTranslation are pointed at the correct alternative.

Covered by nine new specs:
- Seven behavior tests: function leaves, params interpolation, mixed string
  and function leaves, nested dotted-key lookup, shouldMerge=true additive,
  shouldMerge=false replacing, and onTranslationChange event payload.
- Two compiler-bypass spy tests using a local SpyCompiler: a negative
  assertion proves setCompiledTranslation does NOT invoke compileTranslations,
  and a positive control proves setTranslation DOES invoke it exactly once
  on the same compiler instance.

Closes #1605

Author: CodeAndWeb

projects/ngx-translate/src/lib/translate.service.interface.ts

@@ -113,6 +113,12 @@ export abstract class ITranslateService {
         shouldMerge?: boolean,
     ): void;
 
+    public abstract setCompiledTranslation(
+        lang: Language,
+        translations: InterpolatableTranslationObject,
+        shouldMerge?: boolean,
+    ): void;
+
     public abstract getParsedResult(
         key: string | string[],
         interpolateParams?: InterpolationParameters,

projects/ngx-translate/src/lib/translate.service.ts

@@ -347,8 +347,13 @@ export class TranslateService implements ITranslateService {
     }
 
     /**
-     * Manually sets an object of translations for a given language
-     * after passing it through the compiler
+     * Manually sets an object of translations for a given language,
+     * passing it through the configured {@link TranslateCompiler} first.
+     *
+     * If you already have translations in their final compiled form
+     * (e.g. interpolation functions produced at build time), use
+     * {@link setCompiledTranslation} instead — it stores the data
+     * directly and skips the compiler.
      */
     public setTranslation(
         lang: Language,
@@ -360,6 +365,23 @@ export class TranslateService implements ITranslateService {
         this.store.setTranslations(lang, interpolatableTranslations, shouldMerge);
     }
 
+    /**
+     * Stores an already-compiled translation object for the given language,
+     * bypassing the configured {@link TranslateCompiler}.
+     *
+     * Use this when you have translations in their final, interpolator-ready
+     * form — e.g. interpolation functions produced at build time. For raw
+     * translations that still need to go through the compiler, use
+     * {@link setTranslation} instead.
+     */
+    public setCompiledTranslation(
+        lang: Language,
+        translations: InterpolatableTranslationObject,
+        shouldMerge = false,
+    ): void {
+        this.store.setTranslations(lang, translations, shouldMerge);
+    }
+
     public getLangs(): readonly Language[] {
         return this.store.getLanguages();
     }

projects/ngx-translate/src/tests/translate.service.spec.ts

@@ -3,11 +3,14 @@ import { fakeAsync, TestBed, tick } from "@angular/core/testing";
 import { defer, EMPTY, Observable, of, throwError, timer, zip } from "rxjs";
 import { first, map, take, toArray } from "rxjs/operators";
 import {
+    InterpolatableTranslationObject,
     InterpolationParameters,
     LangChangeEvent,
     provideChildTranslateService,
+    provideTranslateCompiler,
     provideTranslateLoader,
     provideTranslateService,
+    TranslateCompiler,
     TranslateLoader,
     TranslatePipe,
     TranslateService,
@@ -722,6 +725,150 @@ describe("TranslateService", () => {
         });
     });
 
+    describe("setCompiledTranslation()", () => {
+        it("stores a function-valued translation and resolves it via instant()", () => {
+            translate.setCompiledTranslation("en", {
+                GREETING: () => "hello",
+            });
+            translate.use("en");
+
+            expect(translate.instant("GREETING")).toBe("hello");
+        });
+
+        it("passes interpolation params to function leaves", () => {
+            translate.setCompiledTranslation("en", {
+                GREETING: (params) => `hello ${params?.["name"] ?? ""}`.trim(),
+            });
+            translate.use("en");
+
+            expect(translate.instant("GREETING", { name: "Andreas" })).toBe("hello Andreas");
+        });
+
+        it("supports mixed string and function leaves in the same object", () => {
+            translate.setCompiledTranslation("en", {
+                STATIC: "plain text",
+                DYNAMIC: (params) => `value: ${params?.["v"]}`,
+            });
+            translate.use("en");
+
+            expect(translate.instant("STATIC")).toBe("plain text");
+            expect(translate.instant("DYNAMIC", { v: 42 })).toBe("value: 42");
+        });
+
+        it("supports nested objects with function leaves reached by dotted keys", () => {
+            translate.setCompiledTranslation("en", {
+                user: {
+                    profile: {
+                        greeting: (params) => `hi ${params?.["name"]}`,
+                    },
+                },
+            });
+            translate.use("en");
+
+            expect(translate.instant("user.profile.greeting", { name: "Rook" })).toBe("hi Rook");
+        });
+
+        it("merges into existing translations when shouldMerge is true", () => {
+            translate.setTranslation("en", { KEEP: "kept string" });
+            translate.setCompiledTranslation("en", { ADDED: () => "added via compiled" }, true);
+            translate.use("en");
+
+            expect(translate.instant("KEEP")).toBe("kept string");
+            expect(translate.instant("ADDED")).toBe("added via compiled");
+        });
+
+        it("replaces existing translations when shouldMerge is false (default)", () => {
+            translate.setTranslation("en", { GONE: "will be replaced" });
+            translate.setCompiledTranslation("en", {
+                REPLACED: () => "new content",
+            });
+            translate.use("en");
+
+            expect(translate.instant("REPLACED")).toBe("new content");
+            // The original key is gone after replacement
+            expect(translate.instant("GONE")).toBe("GONE");
+        });
+
+        it("emits onTranslationChange when storing compiled translations", () => {
+            translate.use("en");
+            const events: TranslationChangeEvent[] = [];
+            const sub = translate.onTranslationChange.subscribe((event) => {
+                events.push(event);
+            });
+
+            translate.setCompiledTranslation("en", {
+                GREETING: () => "hi",
+            });
+
+            sub.unsubscribe();
+            expect(events.length).toBe(1);
+            expect(events[0].lang).toBe("en");
+            expect(typeof (events[0].translations as Record<string, unknown>)["GREETING"]).toBe(
+                "function",
+            );
+        });
+    });
+
+    describe("setCompiledTranslation() compiler bypass", () => {
+        let spyTranslate: TestableTranslateService;
+        let compileTranslationsSpy: jasmine.Spy;
+
+        class SpyCompiler extends TranslateCompiler {
+            compile(value: string, lang: string): string {
+                void lang;
+                return value;
+            }
+            compileTranslations(
+                translations: InterpolatableTranslationObject,
+                lang: string,
+            ): InterpolatableTranslationObject {
+                void lang;
+                return translations;
+            }
+        }
+
+        beforeEach(() => {
+            TestBed.resetTestingModule();
+            TestBed.configureTestingModule({
+                providers: [
+                    provideTestableTranslateService({
+                        loader: provideTranslateLoader(FakeLoader),
+                        compiler: provideTranslateCompiler(SpyCompiler),
+                    }),
+                ],
+            });
+            spyTranslate = TestBed.inject(TranslateService) as TestableTranslateService;
+            compileTranslationsSpy = spyOn(
+                spyTranslate.getCompiler() as SpyCompiler,
+                "compileTranslations",
+            ).and.callThrough();
+        });
+
+        it("does NOT invoke the compiler when storing compiled translations", () => {
+            spyTranslate.setCompiledTranslation("en", {
+                GREETING: () => "hi",
+            });
+            // use() short-circuits via store.hasTranslationFor, so it does NOT
+            // trigger the loader/compiler path here — we're only exercising
+            // setCompiledTranslation / setTranslation.
+            spyTranslate.use("en");
+
+            expect(compileTranslationsSpy).not.toHaveBeenCalled();
+            expect(spyTranslate.instant("GREETING")).toBe("hi");
+        });
+
+        it("DOES invoke the compiler when setTranslation is called, as a control", () => {
+            spyTranslate.setTranslation("en", { GREETING: "hi" });
+            // use() short-circuits via store.hasTranslationFor, so it does NOT
+            // trigger the loader/compiler path here — we're only exercising
+            // setCompiledTranslation / setTranslation.
+            spyTranslate.use("en");
+
+            expect(compileTranslationsSpy).toHaveBeenCalledTimes(1);
+            expect(spyTranslate.instant("GREETING")).toBe("hi");
+        });
+    });
+
     it("should trigger an event when the lang changes", () => {
         const tr: TranslationObject = { TEST: "This is a test" };
         translate.setTranslation("en", tr);