Feature: Add i18n module

package.json

@@ -22,6 +22,7 @@
 		"prepare": "husky install",
 		"cookie-db:update": "node scripts/update-cookie-db.cjs",
 		"rws-json:update": "node scripts/update-rws-json.cjs",
+		"merge-i18n-messages": "node packages/i18n/scripts/merge-messages.cjs",
 		"storybook": "storybook dev -p 6006",
 		"build-storybook": "storybook build",
 		"start": "npm install && npm run dev"

packages/cli/tsconfig.json

@@ -9,5 +9,5 @@
     "esModuleInterop": true,
     "moduleResolution": "node"
   },
-  "references": [{ "path": "../common" }]
+  "references": [{ "path": "../common" }, { "path": "../i18n" }]
 }

packages/i18n/.eslintrc.json

@@ -0,0 +1,6 @@
+{
+  "rules": {
+    "no-console": "off"
+  },
+  "ignorePatterns": ["dist/**", "dist-types/**"]
+}

packages/i18n/README.md

@@ -0,0 +1,5 @@
+# i18n
+
+## Description
+
+A package that handles internationalization and localization.

packages/i18n/_locales/messages/en/messages.json

@@ -0,0 +1,16 @@
+{
+  "testString": {
+    "message": "Testing $details$ with $format$",
+    "description": "This is a test string",
+    "placeholders": {
+      "details": {
+        "content": "$2",
+        "example": "Details of the test"
+      },
+      "format": {
+        "content": "$1",
+        "example": "Format of the test"
+      }
+    }
+  }
+}

packages/i18n/package.json

@@ -0,0 +1,30 @@
+{
+  "name": "@ps-analysis-tool/i18n",
+  "version": "0.6.0",
+  "description": "A package that handles internationalization and localization.",
+  "main": "./dist/index.js",
+  "types": "./dist-types/index.d.ts",
+  "source": "./src/index.ts",
+  "customExports": {
+    ".": {
+      "default": "./src/index.ts"
+    }
+  },
+  "scripts": {
+    "build": "tsc --build",
+    "dev": "tsc-watch --build"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/GoogleChromeLabs/ps-analysis-tool"
+  },
+  "author": "",
+  "license": "Apache-2.0",
+  "bugs": {
+    "url": "https://github.com/GoogleChromeLabs/ps-analysis-tool/issues"
+  },
+  "homepage": "https://github.com/GoogleChromeLabs/ps-analysis-tool",
+  "dependencies": {
+    "intl-messageformat": "^10.5.11"
+  }
+}

packages/i18n/scripts/merge-messages.cjs

@@ -0,0 +1,55 @@
+/*
+ * Copyright 2023 Google LLC
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     https://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+/**
+ * External dependencies.
+ */
+const fs = require('fs');
+
+const PACKAGES = [
+  'cli',
+  'cli-dashboard',
+  'common',
+  'design-system',
+  'extension',
+];
+const COMMON_PATH = 'packages/i18n/_locales';
+const TARGET = `${COMMON_PATH}/messages/en/messages.json`;
+
+const main = () => {
+  fs.writeFileSync(TARGET, '{}');
+
+  const messages = {};
+
+  PACKAGES.forEach((pkg) => {
+    const path = `${COMMON_PATH}/packages/${pkg}/messages.json`;
+    const data = fs.readFileSync(path, 'utf8') || '{}';
+    const parsed = JSON.parse(data);
+
+    Object.entries(parsed).forEach(([key, value]) => {
+      if (messages[key]) {
+        throw new Error(
+          `Duplicate key: ${key}, found in ${pkg}. Please resolve this conflict before continuing.`
+        );
+      }
+
+      messages[key] = value;
+    });
+  });
+
+  fs.writeFileSync(TARGET, JSON.stringify(messages, null, 2));
+};
+
+main();

packages/i18n/src/i18n.ts

@@ -0,0 +1,177 @@
+/*
+ * Copyright 2023 Google LLC
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     https://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+/**
+ * External dependencies.
+ */
+import { existsSync, readFileSync } from 'fs';
+import { IntlMessageFormat } from 'intl-messageformat';
+
+/**
+ * Class representing Internationalization (i18n) functionality.
+ */
+class I18n {
+  private messages: {
+    [key: string]: {
+      message: string;
+      description: string;
+      placeholders: {
+        [key: string]: {
+          content: string;
+          example: string;
+        };
+      };
+    };
+  } = {};
+
+  /**
+   * Initializes the messages object with the provided messages.
+   * @param {object} messages - The messages object containing translations.
+   */
+  initMessages(messages = {}) {
+    this.messages = messages;
+  }
+
+  /**
+   * Creates an array of possible locale strings based on the provided locale.
+   * @param {string} locale - The locale string.
+   * @returns {string[]} An array of locale strings.
+   */
+  private createLocaleArray(locale: string) {
+    return [locale, locale.split('-')[0], locale.split('_')[0], 'en'];
+  }
+
+  /**
+   * Asynchronously loads messages data for the dashboard.
+   * @param {string} locale - The locale string.
+   * @returns {Promise<void>} A promise that resolves when messages are loaded.
+   */
+  async loadDashboardMessagesData(locale: string) {
+    const localeArray = this.createLocaleArray(locale);
+
+    let idx = 0;
+
+    const fetchWithRetry = async () => {
+      if (idx >= localeArray.length) {
+        return;
+      }
+
+      try {
+        const response = await fetch(
+          `/_locales/${localeArray[idx]}/messages.json`
+        );
+
+        if (!response.ok) {
+          throw new Error(
+            `Failed to fetch messages for locale ${localeArray[idx]}`
+          );
+        }
+
+        const data = await response.json();
+
+        this.initMessages(data);
+      } catch (error) {
+        idx++;
+        await fetchWithRetry();
+      }
+    };
+
+    await fetchWithRetry();
+  }
+
+  /**
+   * Loads messages data for the CLI.
+   * @param {string} locale - The locale string.
+   */
+  loadCLIMessagesData(locale: string) {
+    const localeArray = this.createLocaleArray(locale);
+
+    for (const _locale of localeArray) {
+      if (
+        existsSync(`packages/i18n/_locales/messages/${_locale}/messages.json`)
+      ) {
+        const messages = JSON.parse(
+          readFileSync(
+            `packages/i18n/_locales/messages/${_locale}/messages.json`,
+            {
+              encoding: 'utf-8',
+            }
+          )
+        );
+
+        this.initMessages(messages);
+        break;
+      }
+    }
+  }
+
+  /**
+   * Retrieves a translated message for a given key.
+   * @param {string} key - The key of the message to retrieve.
+   * @param {string[]} [substitutions] - An array of substitution values for placeholders in the message.
+   * @param {boolean} [escapeLt] - Whether to escape '<' characters.
+   * @returns {string} The translated message.
+   */
+  getMessage(key: string, substitutions?: string[], escapeLt?: boolean) {
+    if (typeof chrome !== 'undefined' && chrome?.i18n?.getMessage) {
+      // @ts-ignore - Outdated definition.
+      return chrome.i18n.getMessage(key, substitutions, {
+        escapeLt: Boolean(escapeLt),
+      });
+    }
+
+    return this._parseMessage(key, substitutions, escapeLt);
+  }
+
+  /**
+   * Parses a message with substitutions and placeholders.
+   * @param {string} key - The key of the message to parse.
+   * @param {string[]} [substitutions] - An array of substitution values for placeholders in the message.
+   * @param {boolean} [escapeLt] - Whether to escape '<' characters.
+   * @returns {string} The parsed message.
+   */
+  private _parseMessage(
+    key: string,
+    substitutions?: string[],
+    escapeLt?: boolean
+  ) {
+    const messageObj = this.messages?.[key];
+
+    if (!messageObj) {
+      return '';
+    }
+
+    const message = messageObj.message
+      .split('$')
+      .map((part, idx) => (idx % 2 ? `{${part}}` : part))
+      .join('');
+
+    const placeholders = Object.entries(messageObj.placeholders || {}).reduce<{
+      [key: string]: string;
+    }>((acc, [placeholderKey, val]) => {
+      const idx = Number(val.content.substring(1)) - 1;
+
+      acc[placeholderKey] = substitutions?.[idx] || '';
+
+      return acc;
+    }, {});
+
+    return new IntlMessageFormat(message, 'en', undefined, {
+      ignoreTag: escapeLt,
+    }).format(placeholders) as string;
+  }
+}
+
+export default new I18n();

packages/i18n/src/index.ts

@@ -0,0 +1,17 @@
+/*
+ * Copyright 2023 Google LLC
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     https://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+export { default as I18n } from './i18n';