Introduce i18n API for the frontend (#631)

Author: lewisbirks

package-lock.json

@@ -26,6 +26,7 @@
     "@babel/helpers": "^7.20.7",
     "@babel/preset-typescript": "^7.21.0",
     "@babel/traverse": "^7.20.7",
+    "@messageformat/core": "3.4.0",
     "babel-loader": "^9.1.2",
     "babel-plugin-import": "^1.13.6",
     "react": "18.3.1",
@@ -68,7 +69,7 @@
   "jest": {
     "rootDir": "src/main/frontend",
     "setupFilesAfterEnv": [
-      "<rootDir>setupTests.js"
+      "<rootDir>setupTests.ts"
     ],
     "transform": {
       "^.+\\.(ts|tsx)$": "ts-jest"

package.json

@@ -1,7 +1,5 @@
-import {
-  Result,
-  StageInfo,
-} from "../pipeline-graph-view/pipeline-graph/main/PipelineGraphModel";
+import { Result, StageInfo } from "../pipeline-graph-view/pipeline-graph/main";
+import { ResourceBundle } from "./i18n/translations";
 
 export interface RunStatus {
   stages: StageInfo[];
@@ -83,3 +81,23 @@ export async function getConsoleTextOffset(
     return null;
   }
 }
+
+export async function getResourceBundle(
+  resource: string,
+): Promise<ResourceBundle | undefined> {
+  try {
+    const baseUrl: string = document.head.dataset.rooturl ?? "";
+    let response = await fetch(
+      `${baseUrl}/i18n/resourceBundle?baseName=${resource}`,
+    );
+    if (!response.ok) {
+      throw response.statusText;
+    }
+    return (await response.json()).data;
+  } catch (e) {
+    console.error(
+      `Caught error when fetching resource bundle ${resource}: '${e}'`,
+    );
+    return undefined;
+  }
+}

src/main/frontend/common/RestClient.tsx

@@ -0,0 +1,28 @@
+import { choiceFormatter } from "./choice-formatter";
+
+describe("Choice formatter", () => {
+  const { formatter: choice } = choiceFormatter;
+
+  it("should select right option", () => {
+    // Base cases
+    expect(choice("0", "en", "0#first|1#second|1<third")).toEqual("first");
+    expect(choice("1", "en", "0#first|1#second|1<third")).toEqual("second");
+    expect(choice("2", "en", "0#first|1#second|1<third")).toEqual("third");
+
+    // No match
+    expect(choice("-1", "en", "0#first|1#second|1<third")).toEqual("first");
+
+    // Floating-point numbers
+    expect(choice("1.5", "en", "1#first|1.5#second|2#third")).toEqual("second");
+
+    // Invalid input
+    expect(choice("abc", "en", "1#first|2#second")).toEqual("first");
+
+    // Boundary conditions
+    expect(choice("1", "en", "1#first|1<second")).toEqual("first");
+    expect(choice("1.0000000001", "en", "1#one|1<second")).toEqual("second");
+
+    // Empty argument
+    expect(() => choice("1", "en", "")).toThrow();
+  });
+});

src/main/frontend/common/i18n/choice-formatter.spec.ts

@@ -0,0 +1,69 @@
+// The library @messageformat/core supports all the Java MessageFormat
+// implementation apart from ChoiceFormat which it states is deprecated,
+// this is a simple attempt at implementing this without any of the required
+// validation as it is expected that this
+// would already have happened to be used within Jelly
+import { CustomFormatter } from "@messageformat/core";
+
+function nextUp(current: number): number {
+  if (isNaN(current) || current === Number.POSITIVE_INFINITY) {
+    return current;
+  }
+  if (current === 0) {
+    return Number.MIN_VALUE;
+  }
+  const next = current + Number.EPSILON;
+  // The final multiplication (current * (1 + Number.EPSILON)) is needed to handle cases where adding
+  // Number.EPSILON to current does not result in a larger number due to floating-point precision limitations.
+  // This ensures that the next representable floating-point number greater than current is returned,
+  // even when current + Number.EPSILON equals current.
+  return next === current ? current * (1 + Number.EPSILON) : next;
+}
+
+type Choice = {
+  value: string;
+  limit: number;
+};
+
+function choice(value: unknown, locale: string, arg: string | null): string {
+  const parts = arg!.split("|");
+  const _value = Number(value);
+  const choices: Choice[] = [];
+  // a simple attempt to copy java.text.ChoiceFormat.applyPattern
+  // we can assume that these are correctly parsed formats as otherwise java code would have complained
+  // so a part is made up of a number and operator and a value
+  // the valid operators are <, ≤, # (which means equal)
+  for (let part of parts) {
+    // let's iterate through the part until we reach an operator
+    for (let i = 0; i < part.length; i++) {
+      const char = part.charAt(i);
+      if (char === "<" || char === "\u2264" || char === "#") {
+        const operator = char;
+        const number = Number(part.substring(0, i));
+        choices.push({
+          value: part.substring(i + 1),
+          limit: operator === "<" ? nextUp(number) : number,
+        });
+        break;
+      }
+    }
+  }
+  // now we copy java.text.ChoiceFormat.format(double, java.lang.StringBuffer, java.text.FieldPosition)
+  let i = 0;
+  for (i = 0; i < choices.length; ++i) {
+    if (!(_value >= choices[i].limit)) {
+      // same as number < choiceLimits, except catches NaN
+      break;
+    }
+  }
+  --i;
+  if (i < 0) {
+    i = 0;
+  }
+  return choices[i].value;
+}
+
+export const choiceFormatter: { arg: "string"; formatter: CustomFormatter } = {
+  arg: "string",
+  formatter: choice,
+};

src/main/frontend/common/i18n/choice-formatter.ts

@@ -0,0 +1,42 @@
+import React, {
+  Context,
+  createContext,
+  FunctionComponent,
+  ReactNode,
+  useEffect,
+  useState,
+} from "react";
+import {
+  defaultTranslations,
+  getTranslations,
+  Translations,
+} from "./translations";
+
+export const I18NContext: Context<Translations> = createContext(
+  new Translations({}),
+);
+
+interface I18NProviderProps {
+  children: ReactNode;
+}
+
+export const I18NProvider: FunctionComponent<I18NProviderProps> = ({
+  children,
+}) => {
+  const locale = document.getElementById("root")?.dataset.userLocale ?? "en";
+  const [translations, setTranslations] = useState<Translations>(
+    defaultTranslations(locale),
+  );
+
+  useEffect(() => {
+    const fetchTranslations = async () => {
+      const translations = await getTranslations(locale);
+      setTranslations(translations);
+    };
+    fetchTranslations();
+  }, []);
+
+  return (
+    <I18NContext.Provider value={translations}>{children}</I18NContext.Provider>
+  );
+};

src/main/frontend/common/i18n/i18n-provider.tsx

@@ -0,0 +1,60 @@
+jest.mock("../RestClient", () => ({
+  getResourceBundle: jest.fn(),
+}));
+
+import { getResourceBundle } from "../RestClient";
+import { getTranslations, messageFormat, Translations } from "./translations";
+
+describe("Translations", () => {
+  describe("Get translation", () => {
+    const fmt = messageFormat("en");
+
+    const translations = new Translations({
+      "Property.name": fmt.compile("{arg} world"),
+    });
+
+    it("should use known mapped message", () => {
+      expect(translations.get("Property.name")({ arg: "hello" })).toEqual(
+        "hello world",
+      );
+    });
+
+    it("should use fallback formatter with unknown property", () => {
+      expect(
+        translations.get("Unknown.property.name")({ arg: "hello" }),
+      ).toEqual("hello");
+    });
+  });
+
+  describe("Get Translations", () => {
+    it("should compile found resource bundle", async () => {
+      (getResourceBundle as jest.Mock).mockResolvedValue({
+        "A.property": "a value",
+        "Another.property": "with another value",
+        "One.more.property": "with {one} more value",
+      });
+      const translations = await getTranslations("en");
+
+      expect(getResourceBundle).toHaveBeenCalledWith("hudson.Messages");
+      expect(getResourceBundle).toHaveBeenCalledWith("hudson.model.Run.index");
+      expect(translations.get("A.property")()).toEqual("a value");
+      expect(translations.get("Another.property")()).toEqual(
+        "with another value",
+      );
+      expect(translations.get("One.more.property")({ one: "some" })).toEqual(
+        "with some more value",
+      );
+    });
+
+    it("should use the default messages if undefined returned", async () => {
+      (getResourceBundle as jest.Mock).mockResolvedValue(undefined);
+
+      const translations = await getTranslations("en");
+
+      expect(translations.get("Util.second")({ 0: 5 })).toEqual("5 sec");
+      expect(translations.get("Util.day")({ 0: 1 })).toEqual("1 day");
+      expect(translations.get("Util.day")({ 0: 2 })).toEqual("2 days");
+      expect(translations.get("A.property")()).toEqual("");
+    });
+  });
+});