Main menu

Hooks

Notifying external systems when changes occur

This feature is currently in Beta. Please request access.

Adding a hook

  • Open the developer tools modal from any project view where you see the :wrench icon:
  • Switch to the "Hooks" tab, and click the "New hook" link

Choose from one of the following options:

  • Web Hook - Your own hosted endpoint for reacting to translation changes.
  • Amazon SNS - AWS Simple Notification Service can fan out to further actions.

See the links above for their specific options. What follows are the options for notifying any type of hook.

General options

  • Frequency
    This restricts how often (at most) a hook can be notified. The most frequent (continuous) will still be a maximum of every minute or so. If your project doesn't change, no hooks are notified. See triggers below, and general help with task scheduling.

  • Locales
    This filters the locales that are examined for translation changes. You may want an endpoint (for example) for only detecting changes in your source language.

Notification payloads

When changes are detected in your translation project a payload is posted (as the request body) to your configured endpoint. The payload is a JSON object that looks like the example below (simplified):

{
    "notification": {
        "type": "update"
    },
    "project": {
        "url": "https://localise.biz/foo/bar",
    },
    "locales": [
        /* modified locales here */
    ]
}

Each object in the "locales" array is an object as documented in the Locales API. Locales absent from the array are those that have not been changed since the last time the hook was previously notified.

Currently this is the only type of notification that Loco sends, and any change to any part of your project will trigger it. As such, each update is not a discreet "event". Notifications should be thought of as periodic signals that the project state has changed and new files may need exporting.

Notification triggers

Loco detects "changes" as being anything that potentially invalidates exported translation files. That extends to more than just the editing of translations. e.g. Altering project settings, locale settings, source texts - these can all invalidate a file you previously exported.

If you see an empty array of locales in the payload, this indicates that the project has been updated, but no translations were explicitly modified. The notification is still sent, but you can choose to ignore it.

Testing your hook

You can force a notification to fire on demand from the Developer Tools modal where you see the :play icon:

Doing so simulates a full project update, so the payload will include all project locales. You can filter that list before running if needed.

Dashboard notifications

Dashboard and email notifications are personal (user-level) notifications, and not to be confused with notification hooks as described here.

If you want to send email notifications via the hooks system, you can use Amazon SNS. This provides email subscriptions to notification channels.

Last updated by