Localizing using the Dyspatch API

You have completed building your email draft and are ready to localize the content! Follow along with this guide to understand a technical workflow example using the Dyspatch API.

This guide uses resources from the API documentation to help outline which endpoints to use for each step in a programmatic localizations workflow. For more information on each endpoint, take a look at the Drafts API section.

Localizing Email State

In order to start this process, you will want to make sure your email draft is in the Localizing state.

To move to the Localizing draft state, select the Localizations tab and click on the Lock for Translation button.

Lock for translation

There will be a marker to indicate the draft has been successfully locked for translations with the Localizing badge.

Localizing Badge Marker

The draft is now locked to prevent any changes from being made during the translation process. These drafts are tagged specifically to allow your system to pull drafts in this state through the API.

Get Drafts via API

Once the email draft is marked as Localizing, the draft is made available through the API. To retrieve a list of all drafts ready for translation, make a request to the /drafts API with the awaitingLocalization query parameter.

Request URL:

GET https://api.dyspatch.io/drafts?status=awaitingTranslation

Response:

{
  "cursor": {
    "hasMore": false,
    "next": ""
  },
  "data": [
    {
      "createdAt": "2023-03-01T18:57:06Z",
      "id": "tdft_01ds66130r2t2z4h47p7dt4",
      "name": "First Draft - Localizations",
      "path": "fdr_01hpj7ccxzfcg1m1d4oszf3k7s",
      "status": "LOCKED_FOR_TRANSLATION",
      "templateId": "tem_01ds63931fbsgcn0gmgh5zz",
      "templateName": "Tutorial Step 1: Using the Email Builder",
      "updatedAt": "2023-03-01T23:01:13Z",
      "url": "https://api.dyspatch.io/drafts/tdft_01ds66130r2t2z4h47p7dt4"
      "workspaceId": "fdr_01hpj7ccxzdcg1m1d3mszf3k3s"
    },
    ...
  ]
}

Sample Curl Request:

curl --request GET \
  --url 'https://api.dyspatch.io/drafts?status=awaitingTranslation' \
  --header 'accept: application/vnd.dyspatch.2024.08+json' \
  --header 'authorization: Bearer API-KEY'

Replace the API-KEY to use the curl request.

Localizing a Draft

To create a localization for the draft, make a request to the Create/Update a Localization API. The request URL /drafts/{draftId}/localizations/{languageId} will take a draftId and a languageId.

The draftId will be the matching draft ID from the above request. The languageId will be any valid locale code (e.g. "en-US"). Click here for a full list of supported locales.

Sending a request using this endpoint will either overwrite a previously created localization or create a new localization.

Request URL:

PUT https://api.dyspatch.io/drafts/tdft_01ds66130r2t2z4h47p7dt4/localizations/fr-FR

Request Body:

{
	"name": "French (France)"
}

Response:

200 OK

Sample Curl Request:

curl --request PUT \
  --url https://api.dyspatch.io/drafts/tdft_01ds66130r2t2z4h47p7dt4/localizations/fr-FR \
  --header 'accept: application/vnd.dyspatch.2024.08+json' \
  --header 'authorization: Bearer API-KEY' \
  --header 'content-type: application/json' \
  --data '{
	"name": "French (France)"
}'

Replace the Template Draft ID tdft_ and the API-KEY to use the curl request.

Created Localization from API

Get the Localizations Keys for a Draft

Once the localizations have been created on the draft, you will want to fetch the localization keys.

A localization key will be a content piece from your email draft. This typically includes content such as copy, but can also include any URLs and image sources. These keys will be the content you will want to translate and send to your translations team.

Set the Accept header to application/vnd.dyspatch.2024.08+json to get a JSON object with the keys.

Set the Accept header to text/vnd.dyspatch.2024.08+x-gettext-translation to get a POT file with the keys.

The 2024.08 will be the version of the API you're targeting. Take a look at which versions are available: API changelog.

Request URL:

GET https://api.dyspatch.io/drafts/tdft_01ds66130r2t2z4h47p7dt4/localizationKeys

Response - JSON object:

[
  {
    "key": "thanks for signing up!"
  },
  {
    "key": "welcome to %(company_brand)s"
  },
  {
    "key": "Verify Account"
  },
  {
    "key": "https://app.dyspatch.io/welcome?lang=en-US",
    "comment": "localization for 'href' property of 'Verify Account'"
  },
]

OR

Response - POT file:

# GENERATED USING DYSPATCH
# FOR HELP CONTACT SUPPORT@DYSPATCH.IO
#
#, fuzzy
msgid ""
msgstr ""
"MIME-Version: 1.0\n"
"Content-Type: text/plain; charset=UTF-8\n"
"Content-Transfer-Encoding: 8bit\n"

#, python-format
msgid "welcome to %(company_brand)s"
msgstr ""

msgid "thanks for signing up!"
msgstr ""

msgid "Verify Account"
msgstr ""

#. localization for 'href' property of 'Verify Account'
msgid "https://app.dyspatch.io/welcome?lang=en-US"
msgstr ""

Sample Curl Request:

JSON Object

curl --request GET \
  --url https://api.dyspatch.io/drafts/tdft_01ds66130r2t2z4h47p7dt4/localizationKeys \
  --header 'accept: application/vnd.dyspatch.2024.08+json' \
  --header 'authorization: Bearer API-KEY' \
  --header 'content-type: application/json'

POT File

curl --request GET \
  --url https://api.dyspatch.io/drafts/tdft_01ds66130r2t2z4h47p7dt4/localizationKeys \
  --header 'accept: text/vnd.dyspatch.2024.08+x-gettext-translation' \
  --header 'authorization: Bearer API-KEY' \
  --header 'content-type: application/json'

Replace the Template Draft ID tdft_ and the API-KEY to use the curl request.

Send for Translations

You now have the localization keys! You will want to send these keys to be translated either by your translations team or a translation service.

Update Translation Values in Dyspatch

After you have translated the keys, you can update the draft by making a request to the Set translations for language endpoint.

Set Content-Type header to application/json for JSON, or text/x-gettext-translation for PO file.

Request URL:

PUT https://api.dyspatch.io/drafts/tdft_01ds66130r2t2z4h47p7dt4/localizations/fr-FR/translations

Request Body - JSON object:

{
	"welcome to %(company_brand)s": "bienvenue en %(company_brand)s",
	"thanks for signing up!": "merci pour l'enregistrement!",
	"Verify Account": "Vérifier le Compte",
	"https://app.dyspatch.io/welcome?lang=en-US": "https://app.dyspatch.io/welcome?lang=fr-FR"
}

or

Request Body - PO file:

# GENERATED USING DYSPATCH
# FOR HELP CONTACT SUPPORT@DYSPATCH.IO
#
#, fuzzy
msgid ""
msgstr ""
"MIME-Version: 1.0\n"
"Content-Type: text/plain; charset=UTF-8\n"
"Content-Transfer-Encoding: 8bit\n"

#, python-format
msgid "welcome to %(company_brand)s"
msgstr "bienvenue en %(company_brand)s"

msgid "thanks for signing up!"
msgstr "merci pour l'enregistrement!"

msgid "Verify Account"
msgstr "Vérifier le Compte"

#. localization for 'href' property of 'Verify Account'
msgid "https://app.dyspatch.io/welcome?lang=en-US"
msgstr "https://app.dyspatch.io/welcome?lang=fr-FR"

Response:

200 OK

Sample Curl Request:

JSON Object

curl -i --request PUT \
  --url https://api.dyspatch.io/drafts/tdft_01ds66130r2t2z4h47p7dt4/localizations/fr-FR/translations \
  --header 'accept: application/vnd.dyspatch.2024.08+json' \
  --header 'authorization: Bearer API-KEY' \
  --header 'content-type: application/json' \
  --data '{
	"welcome to %(company_brand)s": "bienvenue en %(company_brand)s",
	"thanks for signing up!": "merci pour l'\''enregistrement!",
	"Verify Account": "Vérifier le Compte",
	"https://app.dyspatch.io/welcome?lang=en-US": "https://app.dyspatch.io/welcome?lang=fr-FR"
}'

PO File

curl -i --request PUT \
  --url https\://api.dyspatch.io/drafts/tdft_01ds66130r2t2z4h47p7dt4/localizations/fr-FR/translations \
  --header 'Content-Type: text/x-gettext-translation' \
  --header 'Authorization: Bearer API-KEY' \
  --header 'Accept: application/vnd.dyspatch.2024.08+json' \
  --data msgid\ \"\"'
        'msgstr\ \"\"'
        '\"MIME-Version\:\ 1.0\\n\"'
        '\"Content-Type\:\ text/plain\;\ charset\=UTF-8\\n\"'
        '\"Content-Transfer-Encoding\:\ 8bit\\n\"'
        '\#\,\ python-format'
        'msgid\ \"welcome\ to\ \%\(company_brand\)s\"'
        'msgstr\ \"bienvenue\ en\ \%\(company_brand\)s\"'
        'msgid\ \"thanks\ for\ signing\ up\!\"'
        'msgstr\ \"merci\ pour\ l\'enregistrement\!\"'
        'msgid\ \"Verify\ Account\"'
        'msgstr\ \"V\érifier\ le\ Compte\"

Replace the Template Draft ID tdft_ and the API-KEY to use the curl request.

This action will update the specified language code with the translated keys.

Localized Keys Updated

Submit Email for Approval (Optional)

You can optionally submit the email for approval via the API. If you choose not to do this automatically, you can still manually submit for approval via the dashboard.

Request URL:

POST https://api.dyspatch.io/drafts/tdft_01ds66130r2t2z4h47p7dt4/publishRequest

Response:

200 OK

All set! Your email draft will now be waiting for approval. Your email stakeholders will be able to review the email, reject the approval to provide comments and feedback, or approve and publish the draft.

search icon

Didn't find what you're looking for?

Ask our support team, we're here to help!

Contact Support