i18n-resource-generator

Generates ts classes from yml resource bundles using the icu message format

Installation

npm i @coolon/i18n-resource-generator

Typescript Cofniguration

Add the following to your tsconfig.json

    "resolveJsonModule": true,
    "esModuleInterop": true,

Create a directory for your messages

Create a directory for your message files: e.g. apps/my-app/src/i18n

Add a i18n.config.json file to it with the following:

{
  "srcDirs": ["src/app"], // locations to scan for i18n.yml files.
  "outDir": "src/app",    // where to generate the I18n class and locale files
  "class": "I18n",        // optional, but can be a different name. Useful for libraries 
  "customTypeImports": {  // optional, but you'll typically want these with AUP
    "Alert": "import {Alert} from '@coolon/angular-ui-powerups'",
    "Confirm": "import {Confirm} from '@coolon/angular-ui-powerups'",
    "NavItem": "import {NavItem} from '@coolon/angular-ui-powerups'",
    "CommandFace": "import {CommandFace} from '@coolon/angular-ui-powerups'",
    "ColumnTextProperties": "import {ColumnTextProperties} from '@coolon/angular-ui-powerups'"
  }
}

Relative paths are resolved relative to the config file.

Message files

Add one or more yaml files under the paths specified in the config file: e.g.

In my-properties.i18n.uml

plain_messages:
  say_hello: "Hello {name}"

enums:
  place_navigation(Enum):
    home:
      title: "Home"
      icon_name: "home"
    devices:
      title: "Devices"
      icon_name: "device_icon"

custom_types:
  alerts(Alert[]):
    save_failed:
      content:
        - "The save operation failed"
      ok: "Bugger"

    another_message:
      content:
        - "Content can also have"
        - "Multiple lines"
      ok: "Sweet"

  confimrations(Confirm[]):
    discard_changes:
      content:
        - "Discard the changes to {name}"
      ok: "Yes"
      cancel: "Cancel"
      destructive: truee            

Namespaces

The generator will create namespaces based on the file names and directory structure.

<src dir>/                     # Namespace and code usage
    i18n.yml                   # illegal, files in the src root must have an explicit name like my-properties.i18n.yml
    my-properties.i18n.yml     # Uses file name, i.e. I18n.myProperties.<yaml properties>
    components/
      i18n.yml                 # I18n.components.<yaml properties> (plain i18n files use directory as namesapce)
      components.i18n.yml      # I18n.components.<yaml properties> (same name as directory uses directory namespace)
      special.i18n.yml         # I18n.components.special.<yaml properties>

Running the generator

$ i18n-resource-generator --help
Usage: i18n-resource-generator [options] <configFile>

Options:
  -V, --version  output the version number
  -h, --help     output usage information

Add a run script to your package.json In this case we're placing our source files in apps/my-app/ and our generated output in apps/my-app/src/app.

{
    "scripts": {
       "i18n": "i18n-resource-generator apps/my-app/i18n.config.json"
    }
}   

Then run the script.

npm run i18n

Then your output dir with have:

<out dir>/
    i18n.ts
    locals/
        en.json // generated from your yaml files.. don't edit.

Create additional translations inside the locales directory.

Then use I18n.ts in your project:

import {I18n} from "./i18n.ts";

// the "en" locale will be used by default.
const message = I18n.myMessages.plainMessages.sayHello('World!!!');
interactionContext.alert(I18n.customTypes.alerts.saveFailed())

// Register a new locale.
import spanishBundle from "./locales/es.json";
I18n.registerBundle("es", spanishBundle);

// and use it
I18n.setLocale('es');

// get installed locales
I18n.getAvailableLocales().forEach(locale => console.log(locale));

There is also a special message bundle called message-keys that can be loaded which simply uses the messages keys as the text. This bundle doesn't appear in the I18n.getAvailableLocales() result.

// and use it
I18n.setLocale('message-keys');