@oracle/oraclejet-icu-l10n 16.0.0

package/README.md

@@ -0,0 +1,321 @@
+# JET ICU Message Format Parser
+
+This utility parses message bundles written in ICU format and converts them to
+formatter functions to be called by the application to get localized strings.
+
+## Message Bundle Restrictions
+
+- Message bundle files must be JSON, and only top-level properties are supported
+  (no nesting). The string values must follow the ICU format described at
+  http://userguide.icu-project.org/formatparse/messages
+
+- Any keys which start with "@" will be ignored, and will not be written to the
+  output file(s).
+
+### Ex. app-strings.json
+
+```json
+{
+  "greeting": "Hello {name}",
+  "invitation": "{gender_of_host, select, female {{num_guests, plural, ..."
+}
+```
+
+## Usage
+
+Run the `l10nBundleBuilder.js` script with arguments:
+
+```sh
+$ l10nBundleBuilder.js <root-message-bundle.json> <root-bundle-locale> <output-dir>
+```
+
+### Example, running with a root bundle in en-US locale
+
+```sh
+$ l10nBundleBuilder.js --rootDir=resources/nls --bundleName=app-strings.json --locale=en-US --outDir=dist
+```
+
+## Output
+
+The parser reads the given root bundle and converts the message to a TS module
+containing a single default export object. Within the object, each message
+name will be the key to the formatter function.
+
+### Ex. app-strings.ts
+
+```javascript
+const bundle = {
+  "greeting": function(p) { ... },
+  "invitation": function(p) { ... }
+};
+export default bundle;
+```
+
+The AMD output would be
+
+```javascript
+define(["require", "exports"], function (require, exports) {
+  const bundle = {
+    "greeting": function(p) { ... },
+    "invitation": function(p) { ... }
+  };
+  exports.default = bundle;
+});
+```
+
+In addition to the root bundle, the parser will traverse all directories at the
+same level, looking for other NLS directories which contain message bundle files
+whose name matches that of the root bundle. If found, it combines all messages
+starting from the root bundle up to the most specific bundle, with the most specific
+ones taking precendence.
+
+## Custom Hooks
+
+Custom hooks allows an external script to alter the output of the generated bundle.
+For example, if you want each bundle key to return a custom type rather than
+just the plain translation string, define a custom hook JS file and pass it using
+the `--hooks` switch:
+
+```sh
+$ l10nBundleBuilder.js --rootDir=resources/nls --bundleName=app-strings.json --outDir=dist --hooks=./custom-hooks.js
+```
+
+`custom-hooks.js`
+
+```javascript
+module.exports = {
+  typeImport: {
+    CustomMessageType: '../../resources/CustomMessageType'
+  },
+  otherImports: {
+    escape: '../../str',
+    ext: '../../utils'
+  },
+  // remap some of the parameter names to different keys
+  convertor:
+    '(args: ParamsType): CustomMessageType => ({bundle: ext(args.bundleId), key: escape(args.id), params: args.params, value: args.translation})'
+};
+```
+
+The `typeImport` field defines the custom type import that will be added to the
+Typescript file generated. This should use a single key:value mapping that contains
+the type definition for your custom type begin returned.
+
+You can optionally define `otherImports` to include other imports into the bundle.
+This map can contain an unlimited number of imports. In the example above, the
+functions `escape` and `ext` are imported because they're used by the convertor.
+
+The `convertor` string defines the _contents_ of your convertor function that'll
+be run in place of the default behavior of returning just the translation string.
+The return of this function should match the custom type defined by `typeImport`.
+
+> Note the use of the `ParamsType` as the argument to the convertor. This type
+> is automatically added by the bundler to help your convertor understand the type
+> of parameters that it can expect to be called with.
+> `ParamsType` is defined as such, and is included in each bundle file
+>
+> ```javascript
+> type ParamsType = {
+>   bundleId: string,
+>   id: string,
+>   params: { [key: string]: any } | undefined,
+>   translation: string
+> };
+> ```
+
+`CustomMessageType.d.ts`
+
+```typescript
+export declare type CustomMessageType = {
+  bundle: string;
+  key: string;
+  params: { [key: string]: any } | undefined;
+  value: string;
+};
+```
+
+This will produce a bundle with key/values similar to
+
+```javascript
+  "welcome": ():CustomMessageType => convert({bundleId:ext("app-strings.json"),id:escape("welcome"),params:undefined,translation:"Welcome"}),
+```
+
+The `convertor` function takes `ParamsType` and returns a custom object type
+conforming to `CustomMessageType`.
+
+## Options
+
+### **rootDir**
+
+The root directory of your ICU bundles
+
+> ex. `--rootDir=resources/nls`
+
+### **bundleName**
+
+The bundle file name that should be processed
+
+> ex. `--bundleName=app-strings.json`
+
+### **hooks**
+
+A path to a file containing custom hooks
+
+> ex. `--hooks=./hooks.js`
+
+### **locale**
+
+The locale of the root bundle
+
+> ex. `--locale=en-US`
+
+### **outDir**
+
+The directory where the resource bundles will be written
+
+> ex. `--outDir=src/resources/nls`
+
+### **module** _(optional)_
+
+The type of module to produce for the bundles. Supported values are `esm`, `amd`, or `legacy-amd`.
+If not specified, only the original Typescript source files will be produced, and
+no transpilation is performed.
+
+> ex. `--module=esm`
+
+> For backwards compatibility with previous forms of the bundle in AMD, the `legacy-amd` format
+> will produce a bundle with all keys at the root, similar to using named exports. There will also be no
+> TypeScript or type definitions present for the bundle.
+> This option overrides the `--exportType` argument.
+
+### **exportType** _(optional)_
+
+The type of export to be used. Possible values `named` or `default`. If not given,
+`default` is used.
+
+> ex. `--exportType=named`
+>
+> Note that in v2.0.0 of the builder, default exports are used, causing TypeScript
+> to place all of the keys into an object named "default" at the top level. If
+> you want all of the bundle keys at the top-level, use `--exportType=named` to
+> produce
+>
+> ```javascript
+> export greeting = bundle.greeting;
+> export invitation = bundle.invitation;
+> ```
+>
+> and the resulting AMD output
+
+```javascript
+define(['require', 'exports'], function (require, exports) {
+  exports.greeting = bundle.greeting;
+  exports.invitation = bundle.invitation;
+});
+```
+
+### **override** _(optional)_
+
+Indicates the bundle is an override, and only the root locale and those explicitly stated in
+`--supportedLocales` will be built. All other NLS directories will not be processed.
+
+> ex. `--optional --supportedLocales=en`
+
+### **supportedLocales** _(optional)_
+
+A comma-separated list of additional locales to build. If a given locale doesn't
+have a corresponding NLS directory underneath `rootDir`, then it will be built
+using the root bundle.
+
+> ex. `--supportedLocales=en,en-XB`
+
+## Changes in 2.0.0
+
+### AMD output
+
+In 1.0.0, AMD bundles were constructed with
+
+```javascript
+define({ ...bundle contents... })
+```
+
+Default exports now follow ES module format, and contents are underneath the
+`default` property
+
+```javascript
+define(["require", "exports"], function (require, exports) {
+    "use strict";
+    exports.__esModule = true;
+    exports.default = {
+      ...bundle contents...
+    };
+});
+```
+
+### Typescript
+
+All bundles are now created in Typescript and transpiled to their target module
+formats. The TS sources replace the `d.ts` files previously created in 1.0.0, and
+an additional `BundleType` is exported. This type can be imported for type-safe
+usage during design-time.
+
+```javascript
+import type { BundleType as App1Bundle } from './resources/nls/app1bundle';
+import type { BundleType as App2Bundle } from './resources/nls/app2bundle';
+```
+
+Typescript [type imports](https://www.typescriptlang.org/docs/handbook/release-notes/typescript-3-8.html#type-only-imports-and-export)
+are only used during design-time, and removed from the output when transpiled.
+
+## Changes in 2.0.1
+
+### supportedLocales.ts
+
+A new module file is created in `<outDir>/supportedLocales.ts` which exports an
+array of all the supported locales built for the bundle. See `--supportedLocales`
+option above. The array can be imported
+with
+
+```javascript
+import supportedLocales from './&lt;rootDir>/supportedLocales';
+```
+
+## Changes in 2.2.0
+
+Custom hooks implemented. See [Custom Hooks](#custom-hooks) above.
+
+## Changes in 2.3.0
+
+Add the option to declare `--exportType=named` to generate keys at the top level
+of the exports instead of the `default` export type.
+
+## Changes in 16.0.0
+
+### Types in Metadata
+
+Parameter types can be defined in metadata instead of just inferred from the root bundle.
+Keys starting with the `@` character are used to specify metadata, and is associated with the key whose name follows it:
+
+```
+"input_message_error": "Error: {MESSAGE}",
+"@input_message_error": {
+    "placeholders": {
+       "MESSAGE": {
+          "type": "text",
+          "description": "translated error message"
+       }
+    },
+    "description": "Error with an embedded message"
+}
+```
+
+Metadata is optional. It should be supplied in the following cases:
+
+1. The usage of the text placeholder is going to be unclear to the translators, and supplying extra description in the metadata is going to help translators with translating the rest of the message.
+1. A particular placeholder is not being used in the message included in the root/development bundle, but the corresponding parameter should be settable for some other locales
+   1. v2 translation build process will derive parameter type information from the message in the root/development bundle. Type information for any parameters used only in other locales will have to come from metadata.
+
+### Date Time String Format
+
+Date values are to be passed as string parameters to the message bundle. They can be any valid string,
+as defined by [Date time string format](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Date#date_time_string_format).

package/l10nBundleBuilder.js

@@ -0,0 +1,88 @@
+#! /usr/bin/env node
+const path = require('path');
+
+// Extract arguments
+const argsMap = Array.from(process.argv)
+  .slice(2)
+  .reduce((acc, arg) => {
+    // Store --key=value as { key: value }
+    const pair = (arg.split(/^--/)[1] || '').split(/=/);
+    return {
+      ...acc,
+      [pair && pair[0]]: pair && pair[1]
+    };
+  }, {});
+if ('rootDir' in argsMap && 'bundleName' in argsMap && 'locale' in argsMap && 'outDir' in argsMap) {
+  require('./Bundler').build({
+    ...argsMap,
+    override: 'override' in argsMap,
+    additionalLocales: argsMap.supportedLocales && argsMap.supportedLocales.split(',')
+  });
+} else {
+  const procName = path.basename(process.argv[1]);
+  console.warn(
+    `Usage: ${procName} --rootDir=</path/to/bundle-dir> --bundleName=<message-bundle-name.json> --locale=<bundle-locale> --outDir=<output-dir> [--module=amd|esm|ts] [--export=named|default] [--hooks=<path-to-hooks-file>] [--suportedLocales=..,..]
+
+    Required:
+      --rootDir\tThe root directory where the bundle files are contained
+      --bundleName\tThe bundle's filename (basename, without the directory path)
+      --locale\tThe root bundle's locale
+      --outDir\tThe output directory where the built bundle will be written
+    Optional:
+      --module\tProduce bundles as 'esm', 'amd', or 'legacy-amd' modules
+      --exportType\tThe type of export, either 'named' or 'default' (default='default')
+      --hooks\tThe hooks file to use (see example)
+      --override\tIndicates the bundle is an override, and only the root locale and
+      \tthose explicitly stated in [--supportedLocales] will be built.
+      --supportedLocales\tA list of comma-separated additional locales to build. If
+      \ta locale is specified but doesn't have a directory and translation file
+      \tin the rootDir, it will be built using the root translations.
+      \tThis list will be added onto the full list of supportedLocales exported
+      \tfrom the root bundle TS file, which contains locales found in the rootDir.
+
+    Example for root bundle:
+    ${procName} --rootDir=resources/nls --bundleName=bundle-i18n.json --locale=en-US --outDir=dist --module=amd
+
+    Example for override bundle:
+    ${procName} --rootDir=resources/nls --bundleName=bundle-i18n-x.json --override --locale=en-US --outDir=dist --module=amd --supportedLocales=en
+
+    The rootDir should be the root directory where your root resource bundles and
+    NLS directories reside. This directory would contain entries such as:
+
+      - bundle-i18n.json
+      - de
+        - bundle-i18n.json
+        - bundle-i18n-x.json
+      - de-DE
+        - bundle-i18n.json
+        - bundle-i18n-x.json
+
+    Example for hooks:
+    ${procName} --hooks=./custom-hooks.js
+
+    custom-hooks.js:
+    module.exports = {
+      typeImport: { CustomMessageType: './types/custom-message-type' },
+      convertor: \`({ bundleId, id, params, translation }) => ({
+        bundleId,
+        id,
+        params,
+        translation
+      })\`
+    };
+
+    Produces:
+      import { CustomMessageType } from "./types/custom-message-type";
+
+      const bundle = {
+        "greeting": (params: ParamsType): CustomMessageType => ({
+          "bundleId": "my-bundle",
+          "key": "greeting",
+          "params": [],
+          "translation": "Hello!"
+        })
+      };
+      `
+  );
+  process.exit(1);
+}

package/package.json

@@ -0,0 +1,30 @@
+{
+  "name": "@oracle/oraclejet-icu-l10n",
+  "version": "16.0.0",
+  "description": "JET ICU Message Format Parser",
+  "main": "l10nBundleBuilder.js",
+  "scripts": {
+    "clean": "rimraf test/built test_results",
+    "build-types": "tsc --declaration --emitDeclarationOnly --allowJs --skipLibCheck Bundler.js",
+    "test": "jest -c test/jest.config.js"
+  },
+  "author": "",
+  "license": "ISC",
+  "dependencies": {
+    "@formatjs/icu-messageformat-parser": "2.3.1",
+    "fs-extra": "10.1.0",
+    "glob": "7.2.0",
+    "typescript": "5.3.2"
+  },
+  "devDependencies": {
+    "@jest/globals": "29.6.2",
+    "@oracle/oraclejet-test-utils": "workspace:^",
+    "jest": "29.6.2",
+    "jest-environment-jsdom": "29.6.2",
+    "rimraf": "3.0.2",
+    "ts-jest": "29.1.0"
+  },
+  "bin": {
+    "l10nBundleBuilder": "./l10nBundleBuilder.js"
+  }
+}

package/test/bundleTypeTest.ts

@@ -0,0 +1,40 @@
+import * as fsx from 'fs-extra';
+
+import { describe, expect, test } from '@jest/globals';
+
+import { build } from '../Bundler';
+import glob from 'glob';
+import path from 'path';
+
+describe('L10n builder TypeScript tests', () => {
+  const outputRoot = `${__dirname}/built`;
+  const rootDir = `${__dirname}/resources/nls`;
+
+  describe('TS-only output', () => {
+    const outDir = path.resolve(outputRoot, 'ts');
+    beforeAll(() => {
+      fsx.removeSync(outDir);
+      build({
+        rootDir,
+        bundleName: 'app-strings.json',
+        locale: 'en-US',
+        outDir
+      });
+      build({
+        rootDir,
+        bundleName: 'app-strings-x.json',
+        locale: 'en-US',
+        outDir
+      });
+    });
+
+    test('does not produce JS', () => {
+      expect(glob.sync(`${outDir}/**/*.js`).length).toEqual(0);
+    });
+
+    test('retrieves a value from the TS bundle', async () => {
+      const bundle = (await import(`${outDir}/app-strings`)).default;
+      expect(bundle.testPlural({ itemCount: 2 })).toEqual('You have 2 items');
+    });
+  });
+});

package/test/cliTest.js

@@ -0,0 +1,48 @@
+'use strict';
+const path = require('path');
+const fsx = require('fs-extra');
+const { spawnSync } = require('child_process');
+
+
+describe('CLI', () => {
+  const node = process.argv[0];
+  const outputRoot = path.resolve(__dirname, 'built');
+  const builder = path.resolve(__dirname, '../l10nBundleBuilder.js');
+  const outputDir = path.resolve(outputRoot, 'cli');
+
+  function runBuilder(args) {
+    return spawnSync(node, [builder, ...args], { cwd: __dirname });
+  }
+
+  beforeAll(() => fsx.removeSync(outputDir));
+
+  const args = [
+    `--rootDir=${path.resolve(__dirname, 'resources/nls')}`,
+    '--bundleName=app-strings.json',
+    '--locale=en-US',
+    `--outDir=${outputDir}`
+  ];
+  const omitArg = (name) => (arg) => !arg.startsWith(`--${name}=`);
+
+  const runFailureTest = (...names) => names.forEach(name =>
+    it(`fails with no ${name}`, () => {
+      const build = runBuilder(args.filter(omitArg(name)));
+      expect(build.output[2].toString()).toMatch(/^Usage:/);
+      expect(build.status).toEqual(1);
+    })
+  );
+
+  it('fails with no arguments', () => {
+    const build = runBuilder([]);
+    expect(build.output[2].toString()).toMatch(/^Usage:/);
+    expect(build.status).toEqual(1);
+  });
+
+  runFailureTest('rootDir', 'bundleName', 'locale', 'outDir');
+
+  it('succeeds with required arguments', () => {
+    const build = runBuilder(args);
+    expect(build.output[2].toString()).toEqual('');
+    expect(build.status).toEqual(0);
+  })
+});

package/test/jest.config.js

@@ -0,0 +1,9 @@
+const pkg = require('../package.json');
+const workspaceConfig = require('@oracle/oraclejet-test-utils/workspace-jest-config');
+
+module.exports = workspaceConfig({
+  preset: 'ts-jest',
+  displayName: pkg.name,
+  rootDir: __dirname,
+  testMatch: [ '**/*Test.js', '**/*Test.ts' ]
+});