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.