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

Options | Description | Types -------------------------------|---------------------------------------------------------------------------------------------------|----------- path | Defines the project's key map path | String hookUri | Slack Webhooks API url | String channel (Optional) | Slack channel where will be posted the notification | String username (Optional) | Slack username that will be used to post the notification | String project.name | Project name | String project.boardUrl | It is used to link the notification with your project board (e.g. https://jira.acme.com/browse) | String project.key | Key is the project identifier used to find a task number in a commit message e.g. feat(blog): ACM-0234 :: add comment section | String: "ACM"/ Array: ["ACM", "AMC"] / Regex: /(ACM)-[0-9]+/g messages.title | Slack message title e.g. Changes to Acme dictionary key(s): | String messages.added.description | Slack message description to added keys e.g. Dictionary key ticket_0234 has been added | String messages.added.body | Slack message body to added keys e.g. Text: Hello World | String messages.added.footer | Slack message footer to added keys e.g. Added by John Doe - Task: ACM-0234 | String messages.changed.description | Slack message description to changed keys e.g. Dictionary key ticket_0234 has been changed | String messages.changed.body | Slack message body to changed keys e.g. From: Hello World - To: Hi everyone! | String messages.changed.footer | Slack message footer to changed keys e.g. Changed by John Doe - Task: ACM-0234 | String messages.removed.description | Slack message description to removed keys e.g. Dictionary key ticket_0234 has been removed | String messages.removed.body | Slack message body to removed keys e.g. Text: Hi everyone! | String messages.removed.footer | Slack message footer to removed keys e.g. Removed by John Doe - Task: ACM-0234 | String

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.