Internationalization Specification

Flow

A notification template is changed and submitted for translation. Upon submission, an outbound webhook call will be made that will notify of a pending change submission. Upon receipt of the webhook event, the content for the notification template can be fetched and the translation process begun.

Diagram

{
  type: "notification:submitted",
  data: {
		id: "NOTIFICATION_ID_HERE",
    // ...
  }

Fetching Content

When the “notification:submitted” is received

GET /notifications/:notification_id/draft/content

Sample Template

Sample Template Response

{
  "blocks": [
    {
      "alias": "Greetings",
      "context": "This is where we greet a new user",
      "id": "block_43c114d9-9cfd-4340-808f-17e2fc7a4c87",
      "type": "text",
      "checksum": "fb60f2098fa407a4ff8d48e3e908d889",
      "content": "Hello <variable id=\"3\">{name}</variable>, Welcome to <highlight id=\"6\">Courier</highlight>!",
      "locales": {
        "fr_FR": "Bonjour <variable id=\"3\">{name}</variable>, bienvenu a <highlight id=\"6\">Courier</highlight>!"
      }
    },
    {
      "id": "block_f19dd58f-d32c-41b8-911c-239053d34803",
      "type": "markdown",
      "content": "Ready, <variable id=\"3\">{name}</variable>? Get started [here](http://daringfireball.net/projects/markdown/).",
      "checksum": "d06665ec3f663789db81474bc1a82fc5",
      "locales": {
        "fr_FR": "prêt, <variable id=\"3\">{name}</variable>? Commencer [ici](http://daringfireball.net/projects/markdown/)."
      }
    },
    {
      "id": "block_78863d66-54f2-4032-a897-cbed3abb2538",
      "type": "quote",
      "content": "<highlight id=\"3\">Marvel</highlight> is better than DC, do you agree <variable id=\"6\">{name}</variable>?",
      "checksum": "d6e5df4e00b54703e7048cbc5276863e",
      "locales": {
        "fr_FR": "<highlight id=\"3\">Marvel</highlight> mieux que DC, êtes-vous d'accord <variable id=\"3\">{name}</variable>?"
      }
    },
    {
      "id": "block_106b5136-1bf9-4842-bff7-cbae140fd3a3",
      "type": "action",
      "content": "Share",
      "checksum": "67561c1170434dcbfd9becb827672495",
      "locales": {
        "fr_FR": "Partagez"
      }
    },
    {
      "id": "block_9ec5eba6-8ab1-4938-96b0-0f6b63439619",
      "type": "list",
      "content": {
        "children": "<variable id=\"3\">{userName}</variable>",
        "parent": "<variable id=\"3\">{blogTitle}</variable> liked by"
      },
      "checksum": "a4f817cd1a363e95ce1400095937cad8",
      "locales": {
        "fr_FR": {
          "children": "<variable id=\"3\">{userName}</variable>",
          "parent": "<variable id=\"3\">{blogTitle}</variable> aimé par"
        }
      }
    },
    {
      "id": "block_31500deb-de21-436f-9ae6-98f08d569148",
      "type": "template",
      "content": "\n\n<div class=\"notes\">Thanks!</div>",
      "checksum": "c1a6639e8a83a4aba68004ad1a06f124",
      "locales": {
        "fr_FR": "\n\n<div class=\"notes\">Merci!</div>"
      }
    }
  ],
  "channels": [
    {
      "id": "channel_f2e7b2e9-187f-40d9-9725-636d6c59833a",
      "type": "email",
      "content": {
        "subject": "New Subject"
      },
      "checksum": "96bcf212afa5cae1c7918280743aec71",
      "locales": {
        "fr_FR": {
          "subject": "French New Subject"
        }
      }
    }
  ],
  "checksum": "22d224a20345f1e3d3cf4c231243a747"
}

Block Alias and Context

Every block can optionally have an alias and a context. This can be used to have supplementary block information for organizing blocks better.

Retrieval: GET content endpoints can be used to retrieve alias and context per block

Updates: Can only be changed from the Courier UI by clicking on the block info(i) icon

Template Block Info

Block Info Dialog

Block types supported

Text Block

Example: Text block with a variable {name} and a highlight

Text Block Example

Here’s how the block JSON would look like

{
  "alias": "Greetings",
  "context": "This is where we greet a new user",
  "id": "block_43c114d9-9cfd-4340-808f-17e2fc7a4c87",
  "type": "text",
  "content": "Hello <variable id=\"3\">{name}</variable>, Welcome to <highlight id=\"6\">Courier</highlight>!",
  "locales": {
    "fr_FR": "Bonjour <variable id=\"3\">{name}</variable>, bienvenu a <highlight id=\"6\">Courier</highlight>!"
  }
}

Let’s talk IDs

Block ID: This is the top level ID which every block gets and is prefixed with block.

Variable ID: Unique IDs that a variable inside a block content gets

Highlight ID: Unique IDs that a highlight inside a block content gets

Note - All the IDs are auto-generated by Courier and are used in resolving the contents for the block. The locale variations PUT should also have exactly same IDs for accurate consolidation and resolution.

Quote Block

Example: Quote block with a variable {name} and a highlight

{
  "id": "block_78863d66-54f2-4032-a897-cbed3abb2538",
  "type": "quote",
  "content": "<highlight id=\"3\">Marvel</highlight> is better than DC, do you agree <variable id=\"6\">{name}</variable>?",
  "locales": {
    "fr_FR": "<highlight id=\"3\">Marvel</highlight> mieux que DC, êtes-vous d'accord <variable id=\"3\">{name}</variable>?"
  }
}

Markdown Block

Example: Markdown block with a variable {name}

{
  "id": "block_f19dd58f-d32c-41b8-911c-239053d34803",
  "type": "markdown",
  "content": "Ready, <variable id=\"3\">{name}</variable>? Get started [here](http://daringfireball.net/projects/markdown/).",
  "locales": {
    "fr_FR": "prêt, <variable id=\"3\">{name}</variable>? Commencer [ici](http://daringfireball.net/projects/markdown/)."
  }
}

Action Block

{
  "id": "block_106b5136-1bf9-4842-bff7-cbae140fd3a3",
  "type": "action",
  "content": "Share it",
  "locales": {
    "fr_FR": "Partagez-le"
  }
}

List Block

List blocks can get a bit confusing - an article that can help an article that can help

{
  "id": "block_9ec5eba6-8ab1-4938-96b0-0f6b63439619",
  "type": "list",
  "content": {
    "children": "<variable id=\"3\">{userName}</variable>",
    "parent": "<variable id=\"3\">{blogTitle}</variable> liked by"
  },
  "locales": {
    "fr_FR": {
      "children": "<variable id=\"3\">{userName}</variable>",
      "parent": "<variable id=\"3\">{blogTitle}</variable> aimé par"
    }
  }
}

Template Block

{
  "id": "block_31500deb-de21-436f-9ae6-98f08d569148",
  "type": "template",
  "content": "\n\n<div class=\"notes\">Thanks!</div>"
  },
  "locales": {
     "fr_FR": "\n\n<div class=\"notes\">Merci!</div>"
  }
}

Note: We intentionally omit styles and comments in the API response to optimize the translation payload

Checksum

We md5 hash the contents for each block, channel and notification so you could track if contents have ever changed in order to manage translations workflow as needed.

Channels

We expose the email (subject) and push (title) to be localized (assuming you have those channels configured with your notification)

Updating Content

When translated content is received, template content should be fetched and the new content should be overlaid. This can be repeated each time a piece of translated content is received.

PUT /notifications/:notification_id/draft/locales

{
  "blocks": [
    {
      "id": "block_43c114d9-9cfd-4340-808f-17e2fc7a4c87",
      "type": "text",
      "locales": {
        "fr_FR": "Bonjour <variable id=\"3\">{name}</variable>, bienvenu a <highlight id=\"6\">Courier</highlight>!"
      }
    },
    {
      "id": "block_78863d66-54f2-4032-a897-cbed3abb2538",
      "type": "quote",
      "locales": {
        "fr_FR": "<highlight id=\"3\">Marvel</highlight> mieux que DC, êtes-vous d'accord <variable id=\"3\">{name}</variable>?"
      }
    },
    {
      "id": "block_f19dd58f-d32c-41b8-911c-239053d34803",
      "type": "markdown",
      "locales": {
        "fr_FR": "prêt, <variable id=\"3\">{name}</variable>? Commencer [ici](http://daringfireball.net/projects/markdown/)."
      }
    },
    {
      "id": "block_106b5136-1bf9-4842-bff7-cbae140fd3a3",
      "type": "action",
      "locales": {
        "fr_FR": "Partagez-le"
      }
    },
    {
      "id": "block_9ec5eba6-8ab1-4938-96b0-0f6b63439619",
      "type": "list",
      "locales": {
        "fr_FR": {
          "children": "<variable id=\"3\">{userName}</variable>",
          "parent": "<variable id=\"3\">{blogTitle}</variable> aimé par"
        }
      }
    },
    {
      "id": "block_31500deb-de21-436f-9ae6-98f08d569148",
      "type": "template",
      "locales": {
        "fr_FR": "\n\n<div class=\"notes\">Merci!</div>"
      }
    }
  ]
}

Updating partial contents

In case you’d like to update a specific block or a channel’s locales, or all blocks and channels for a specific locale (for ex: Chinese translations for a notification), we’ve got you covered. You can use the following endpoints -

Update locales for a specific block

POST /notifications/:notification_id/blocks/:block_id/locales

or POST /notifications/:id/draft/blocks/:blockId/locales

{
  "fr_FR": "French Lorem Ipsum",
  "it_IT": "Italian Lorem Ipsum"
}

Update locales for a specific channel

POST /notifications/:id/channels/:channelId/locales

or POST /notifications/:id/draft/channels/:channelId/locales

{
  "fr_FR": "French Subject",
  "it_IT": "Italian Subject"
}

Update block and channel contents for a specific locale

PUT /notifications/:id/locales/:localeid

or PUT /notifications/:id/draft/locales/:localeid

{
  "blocks": [
    {
      "id": "block_f4c81f75-8edb-4c8f-a50b-37193a580b7f",
      "content": "Italian text block content"
    },
    {
      "id": "block_fcb968bf-b0d1-48e0-b1b2-e23963de8479",
      "content": {
          "children": "Italian List block children",
          "parent": "Italian List block parent"
      }
    }
  ],
  "channels": [
    {
      "id": "channel_9f24f9a9-c597-4330-b357-7929a6dc8f33",
      "content": "Italian Subject"
    },
    {
      "id": "channel_20dda4a6-5439-4a71-953a-bc70a90e39f5",
      "content": "Italian Push Title"
    }
  ]

Completing The Process

Once all content has been updated, Courier can be notified that the process is completed and release the template to be published.

PUT /notifications/:notification_id/:submission_id/checks

{
  "checks": [
    {
      "id": "B5BYH93H4D4XRPJBMZJGB43TJEZ3", // check ID
      "status": "RESOLVED",
      "type": "custom"
    }
  ]
}

Fetching Checks

Checks API GET endpoint

GET /notifications/:notification_id/:submission_id/checks

Example - GET /notifications/SFTYJKSF0241SVH2TWY97TTFFTQG/1630424150210/checks

{
	"checks":[
		{
			"id":"B5BYH93H4D4XRPJBMZJGB43TJEZ3", // check ID
			"status":"PENDING",
			"type":"custom",
			"updated":1630424150210
		}
	]
}

Locale based preview

Notification Preview section reflects localized content if there’s a locale associated with the profile in your test-event. Here’s an example -

I have "locale": "fr_FR" in the profile object of a test event

Localized Preview

Default Preview (no locale in the profile object of the test event)

Using locales while sending messages

You can use locale as a profile attribute while invoking Courier’s /send endpoint. Here’s an example -

{
	"event": "<your-notification-or-event>",
	"recipient": "<your-recipient>",
	"profile": {
            "locale": "en_US"
         }
}

Webhooks

As mentioned earlier in the doc, you could configure the webhooks in Settings → Webhooks and we’d call those when a notification was submitted for a review, when it was canceled and also when it got published. Please note: At this point we do not have a granular way to allocate webhooks so you could get other events (like message sent events) for the webhooks you add to the Settings, feel free to ignore/not handle those. Here’s a couple of screenshots -

Submitted Keys

Submitted keys are used when you have to send a notification that was submitted for a review but maybe not ready to be published. Basically, submitted is an interim state between Draft and Published. Here’s how it works -

→ If notification was published, a submitted key send operation uses published notification contents

→ If notification was submitted for review, a submitted key send operation uses latest draft notification content

Submitted keys can be retrieved, updated or deleted from the Settings → API Keys UI.

Block overrides

We also expose blocks via overrides object in case you need to override the contents on the fly during the send operations.

Getting Started

Platform

Tools

Internationalization Specification

Flow

Fetching Content

Sample Template

Sample Template Response

Block Alias and Context

Block types supported

Text Block

Let’s talk IDs

Quote Block

Markdown Block

Action Block

List Block

Template Block

Checksum

Channels

Updating Content

Updating partial contents

Update locales for a specific block

Update locales for a specific channel

Update block and channel contents for a specific locale

Completing The Process

Fetching Checks

Locale based preview

Using locales while sending messages

Webhooks

Submitted Keys

Block overrides

Getting Started

Platform

Tools

​Flow

​Fetching Content

​Sample Template

​Sample Template Response

​Block Alias and Context

​Block types supported

​Text Block

​Let’s talk IDs

​Quote Block

​Markdown Block

​Action Block

​List Block

​Template Block

​Checksum

​Channels

​Updating Content

​Updating partial contents

​Update locales for a specific block

​Update locales for a specific channel

​Update block and channel contents for a specific locale

​Completing The Process

​Fetching Checks

​Locale based preview

​Using locales while sending messages

​Webhooks

​Submitted Keys

​Block overrides

Flow

Fetching Content

Sample Template

Sample Template Response

Block Alias and Context

Block types supported

Text Block

Let’s talk IDs

Quote Block

Markdown Block

Action Block

List Block

Template Block

Checksum

Channels

Updating Content

Updating partial contents

Update locales for a specific block

Update locales for a specific channel

Update block and channel contents for a specific locale

Completing The Process

Fetching Checks

Locale based preview

Using locales while sending messages

Webhooks

Submitted Keys

Block overrides