@dictools/notifier v1.0.2

Getting started

Dictools Notifier is a tool used to notifies development/content team using a slack webhook based on a JSON file. Usually, it is used when the development team has the autonomy to create i18n dictionary keys directly in the code using a fallback file, this way it's not necessary to await the content team create the keys before writing the code.

Installation

Dictools Notifier can be installed using npm or yarn:

# npm
npm install @dictools/notifier --save-dev

# yarn
yarn add @dictools/notifier --dev

Usage

Prerequisites:

• Slack Incoming Webhooks
• NodeJS (>=10.x.x)
• Git (>= 2.13.x)
• Dictools Notifier should be used along with Git Hooks [ post-commit ] to recover information and compare your dictionary file. The library does not include built-in hooks, we recommend to use a third-party library like husky or build your own hooks

Script Initializer

Create a configuration file to start using dictools/notifier. The message can be formatted using the attachment format provided by slack, to know more details please check out the documentation.

// notification.js
const Notifier = require("@dictools/notifier");

const notification = new Notifier({
  path: "dictionary.json", // JSON file only
  hookUri: "https://hooks.slack.com/services/<api_token>",
  channel: "#acme-keys", // Optional
  username: "Acme", // Optional
  project: {
    name: "Acme App",
    boardUrl: "https://jira.acme.com/browse",
    key: "ACM" // (e.g. Task number ACM-0234)
  }
  /** 
   * Optional Configuration: ( Slack message replacement )
   * Text has available replacement keys that is used to get information from the project or git diff
   * and it can be customized as you need.
   */
  messages: {
    /** 
     * Check out the available text keys
     * @param {string} #{project} - Project name
     * @param {string} #{key} - Dictionary key name
     * @param {string} #{type} - Git change type (e.g. Added, Changed, Removed)
     * @param {string} #{username} - Git committer name (Global or locally git username)
     * @param {string} #{task} - Task link for the board (e.g. https://jira.acme.com/browse/ACM-0234)
     * @param {string} #{value} - Current content key value
     * @param {string} #{oldValue} - Previous content key value
     */
    title: "Changes to #{project} dictionary key(s):",
    added: {
      description: "Dictionary key #{key} has been #{type}",
      body: "Text: #{value}",
      footer: "#{type} by: #{username} | Task: #{task}"
    },
    changed: {
      description: "Dictionary key *#{key}* has been #{type}",
      body: "From: #{oldValue} To: #{value}",
      footer: "#{type} by: #{username} | Task: #{task}"
    },
    removed: {
      description: "Dictionary key *#{key}* has been #{type}",
      body: "Text: #{value}",
      footer: "#{type} by: #{username} | Task: #{task}"
    }
  }
});

notification.init();

Options

Configure Git Hooks

Let's see an example using Husky.

// package.json
{
  "husky": {
    "hooks": {
      "post-commit": "node ./notification.js"
    }
  }
}

After setting up the hook start to commit normally and as soon as you have new changes to the dictionary you will receive a notification on the configured slack channel.

Slack message preview

Contributing

Thanks for being interested in helping us to improve the experience for who use this library, we are all ears to listen, if you want to collaborate reporting an issue, feature or something else please use the issues section using the proper labels to your request, we will answer as soon as we can, thank you!

License

Dictools Notifier is MIT licensed.