Template translations

Add a locale to a Template and Courier picks it per recipient at send time.

How it works

When message.to includes a locale, Courier replaces default property values with that locale’s translations. Elements with no matching locale definition keep their defaults. The locale interface:

interface Locales {
  [locale: string]: {
    content?: string;      // text, action, quote, html
    title?: string;        // meta
    href?: string;         // action, image
    src?: string;          // image
    raw?: Record<string, unknown>; // channel (provider-native overrides)
    elements?: Element[];  // shape varies by element type, see above
  };
}

Text node resolution

Text elements accept two content formats: content (a plain or markdown string) and elements (a structured array of inline nodes like string, link, and img). Locales handle every combination:

Root node has	Locale provides	Behavior
`content`	`content`	Replaces the content string
`elements`	`elements`	Replaces the elements array
`elements`	`content`	Wraps the content string into a single-element array for backward compatibility
`content` + `elements`	`content` + `elements`	Uses `elements` (structured format takes precedence)
`content` + `elements`	`content` only	Wraps the content string into a single-element array
`content` + `elements`	`elements` only	Uses the locale’s elements array

If a locale translation is missing for an element, Courier falls back to the default property value. Notifications still render when translations are incomplete.

When a text node uses the elements format and a locale provides only a content string, Courier wraps the string into a single-element array ([{ type: "string", content: "..." }]). Rendering survives, but any inline formatting (bold, italic, links) in the original elements is lost. Provide elements in your locale translations to keep formatting.

Why use locales

Single template, multiple languages: One structure and logic, with translated text per locale
Automatic selection: Courier uses the recipient’s locale from their profile or the message.to.locale field
Fallback support: If a translation is missing, Courier uses the default content

Supported elements and properties

Which properties accept a locale override depends on the element type:

content: Text content in text, action, quote, and html elements
title: Title in meta elements (email subject lines, push notification titles)
href: URLs in action and image elements
src: Image source URLs in image elements
raw: Provider-native channel overrides in channel elements, such as a translated subject or an entire translated html body
elements: Nested elements. The accepted shape varies by type:
- inline nodes (string, link, img) in text and list-item
- full nodes in channel, group, and column
- column nodes in columns
- list-item nodes in list

divider, jsonnet, partial, and comment elements reject any locale override. Sending a property that an element type does not support returns a 400 naming the field.

Add translations

Add a locale in the designer

Open the template, add a locale (like fr or pt-BR), and enter the translated content for each element. Courier stores per-locale content on the template, so the structure stays shared and only the text differs.

Or set it via the API

Write a locale’s content with or the put-locale CLI verb. Use this to keep translations in your own system and sync them in.

Translate with AI

Courier’s AI translation generates a locale’s content from your base content, which you then review and edit. This is a console feature. Run it per template when you add or update a locale.AI translation needs the Business or Enterprise plan. Each translation costs 2.5 AI credits plus token overages, drawn from the same balance as . With no credits the console reports that translation requires them.

Send to a localized recipient

Set a test user’s profile.locale to a locale you localized and send the template. Confirm the localized content renders in . Then send to a user without that locale and confirm the base content renders.

Workspace translation strings

Workspace translations hold short strings reused across templates, like button labels and common phrases. They are keyed by locale and rendered with the {{t}} Handlebars helper. Manage them with and reference a string with {{t "welcome_headline"}}. Use this for a shared glossary, and per-locale template content for the body of a notification. Three details decide how you integrate it:

The payload is a .po file, not JSON. That is the gettext format most translation tooling already exports, so a vendor’s output usually needs no conversion.
domain only accepts default today. It exists for future namespacing, and any other value fails.
Read them back with , which returns the stored .po content. Useful for diffing what is live against what your translation system holds.

Translations are per workspace, not per tenant. A cannot override a string, so a customer who needs different wording needs a different template rather than a different translation.

Basic example

Localize a text element:

import Courier from "@trycourier/courier";

const courier = new Courier({
  apiKey: process.env.COURIER_API_KEY,
});

const { requestId } = await courier.send.message({
  message: {
    to: {
      email: "sarah@acme-corp.com",
      locale: "fr",
    },
    content: {
      version: "2022-01-01",
      elements: [
        {
          type: "text",
          content: "Hello",
          locales: {
            fr: {
              content: "Bonjour",
            },
            es: {
              content: "Hola",
            },
          },
        },
      ],
    },
  },
});

console.log(`Sent with request ID: ${requestId}`);

import os
from courier import Courier

client = Courier(api_key=os.environ["COURIER_API_KEY"])

response = client.send.message(
    message={
        "to": {
            "email": "sarah@acme-corp.com",
            "locale": "fr",
        },
        "content": {
            "version": "2022-01-01",
            "elements": [
                {
                    "type": "text",
                    "content": "Hello",
                    "locales": {
                        "fr": {"content": "Bonjour"},
                        "es": {"content": "Hola"},
                    },
                }
            ],
        },
    }
)

print(f"Sent with request ID: {response.request_id}")

curl -X POST https://api.courier.com/send \
  -H "Authorization: Bearer $COURIER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "message": {
      "to": {
        "email": "sarah@acme-corp.com",
        "locale": "fr"
      },
      "content": {
        "version": "2022-01-01",
        "elements": [
          {
            "type": "text",
            "content": "Hello",
            "locales": {
              "fr": {
                "content": "Bonjour"
              },
              "es": {
                "content": "Hola"
              }
            }
          }
        ]
      }
    }
  }'

require "courier"

courier = Courier::Client.new(api_key: ENV["COURIER_API_KEY"])

response = courier.send_.message(
  message: {
    to: {
      email: "sarah@acme-corp.com",
      locale: "fr"
    },
    content: {
      version: "2022-01-01",
      elements: [
        {
          type: "text",
          content: "Hello",
          locales: {
            fr: { content: "Bonjour" },
            es: { content: "Hola" }
          }
        }
      ]
    }
  }
)

puts("Sent with request ID: #{response.request_id}")

// Elemental nodes carry no typed content fields, so pass the document as raw JSON.
content := param.Override[shared.ElementalContentParam](json.RawMessage(`{
  "version": "2022-01-01",
  "elements": [
    {
      "type": "text",
      "content": "Hello",
      "locales": {
        "fr": { "content": "Bonjour" },
        "es": { "content": "Hola" }
      }
    }
  ]
}`))

response, err := client.Send.Message(context.TODO(), courier.SendMessageParams{
	Message: courier.SendMessageParamsMessage{
		To: courier.SendMessageParamsMessageToUnion{
			OfUserRecipient: &shared.UserRecipientParam{
				Email:  courier.String("sarah@acme-corp.com"),
				Locale: courier.String("fr"),
			},
		},
		Content: courier.SendMessageParamsMessageContentUnion{OfElementalContent: &content},
	},
})
if err != nil {
	panic(err.Error())
}

fmt.Printf("Sent with request ID: %s\n", response.RequestID)

SendMessageParams params = SendMessageParams.builder()
    .message(SendMessageParams.Message.builder()
        .to(UserRecipient.builder()
            .email("sarah@acme-corp.com")
            .locale("fr")
            .build())
        // Elemental nodes carry no typed content fields, so pass the document as raw JSON.
        .content(JsonValue.from(java.util.Map.of(
            "version", "2022-01-01",
            "elements", java.util.List.of(
              java.util.Map.of(
                "type", "text",
                "content", "Hello",
                "locales", java.util.Map.of(
                  "fr", java.util.Map.of("content", "Bonjour"),
                  "es", java.util.Map.of("content", "Hola")))))))
        .build())
    .build();
SendMessageResponse response = client.send().message(params);

$response = $client->send->message(
  message: [
    'to' => [
      'email' => 'sarah@acme-corp.com',
      'locale' => 'fr',
    ],
    'content' => [
      'version' => '2022-01-01',
      'elements' => [
        [
          'type' => 'text',
          'content' => 'Hello',
          'locales' => [
            'fr' => ['content' => 'Bonjour'],
            'es' => ['content' => 'Hola'],
          ],
        ],
      ],
    ],
  ],
);

SendMessageParams parameters = new()
{
    Message = new()
    {
        To = new UserRecipient { Email = "sarah@acme-corp.com", Locale = "fr" },
        // Elemental nodes expose no typed content fields, so build the document from raw JSON.
        Content = ElementalContent.FromRawUnchecked(
            JsonSerializer.Deserialize<Dictionary<string, JsonElement>>("""
            {
              "version": "2022-01-01",
              "elements": [
                {
                  "type": "text",
                  "content": "Hello",
                  "locales": {
                    "fr": { "content": "Bonjour" },
                    "es": { "content": "Hola" }
                  }
                }
              ]
            }
            """)),
    },
};

var response = await client.Send.Message(parameters);

courier send message \
  --api-key "$COURIER_API_KEY" \
  --message.to '{"email": "sarah@acme-corp.com", "locale": "fr"}' \
  --message.content '{"version": "2022-01-01", "elements": [{"type": "text", "content": "Hello", "locales": {"fr": {"content": "Bonjour"}, "es": {"content": "Hola"}}}]}'

With Courier MCP, send my greeting to sarah@acme-corp.com with locale fr, and localize it into French and Spanish.

When the recipient’s locale is "fr", "Hello" becomes "Bonjour". When it is "es", it becomes "Hola". Any other locale, or none, renders the default "Hello".

Localizing multiple elements

Localize several element types in one template:

import Courier from "@trycourier/courier";

const courier = new Courier({
  apiKey: process.env.COURIER_API_KEY,
});

const { requestId } = await courier.send.message({
  message: {
    to: {
      email: "sarah@acme-corp.com",
      locale: "es",
    },
    data: {
      user_name: "María",
    },
    content: {
      version: "2022-01-01",
      elements: [
        {
          type: "meta",
          title: "Welcome to our platform",
          locales: {
            es: {
              title: "Bienvenido a nuestra plataforma",
            },
            fr: {
              title: "Bienvenue sur notre plateforme",
            },
          },
        },
        {
          type: "text",
          content: "Thanks for signing up, {{user_name}}!",
          locales: {
            es: {
              content: "¡Gracias por registrarte, {{user_name}}!",
            },
            fr: {
              content: "Merci de vous être inscrit, {{user_name}} !",
            },
          },
        },
        {
          type: "action",
          content: "Get Started",
          href: "https://app.example.com/dashboard",
          locales: {
            es: {
              content: "Comenzar",
              href: "https://app.example.com/es/dashboard",
            },
            fr: {
              content: "Commencer",
              href: "https://app.example.com/fr/dashboard",
            },
          },
        },
      ],
    },
  },
});

console.log(`Sent with request ID: ${requestId}`);

import os
from courier import Courier

client = Courier(api_key=os.environ["COURIER_API_KEY"])

response = client.send.message(
    message={
        "to": {
            "email": "sarah@acme-corp.com",
            "locale": "es",
        },
        "data": {
            "user_name": "María",
        },
        "content": {
            "version": "2022-01-01",
            "elements": [
                {
                    "type": "meta",
                    "title": "Welcome to our platform",
                    "locales": {
                        "es": {"title": "Bienvenido a nuestra plataforma"},
                        "fr": {"title": "Bienvenue sur notre plateforme"},
                    },
                },
                {
                    "type": "text",
                    "content": "Thanks for signing up, {{user_name}}!",
                    "locales": {
                        "es": {"content": "¡Gracias por registrarte, {{user_name}}!"},
                        "fr": {"content": "Merci de vous être inscrit, {{user_name}} !"},
                    },
                },
                {
                    "type": "action",
                    "content": "Get Started",
                    "href": "https://app.example.com/dashboard",
                    "locales": {
                        "es": {
                            "content": "Comenzar",
                            "href": "https://app.example.com/es/dashboard",
                        },
                        "fr": {
                            "content": "Commencer",
                            "href": "https://app.example.com/fr/dashboard",
                        },
                    },
                },
            ],
        },
    }
)

print(f"Sent with request ID: {response.request_id}")

curl -X POST https://api.courier.com/send \
  -H "Authorization: Bearer $COURIER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "message": {
      "to": {
        "email": "sarah@acme-corp.com",
        "locale": "es"
      },
      "data": {
        "user_name": "María"
      },
      "content": {
        "version": "2022-01-01",
        "elements": [
          {
            "type": "meta",
            "title": "Welcome to our platform",
            "locales": {
              "es": {
                "title": "Bienvenido a nuestra plataforma"
              },
              "fr": {
                "title": "Bienvenue sur notre plateforme"
              }
            }
          },
          {
            "type": "text",
            "content": "Thanks for signing up, {{user_name}}!",
            "locales": {
              "es": {
                "content": "¡Gracias por registrarte, {{user_name}}!"
              },
              "fr": {
                "content": "Merci de vous être inscrit, {{user_name}} !"
              }
            }
          },
          {
            "type": "action",
            "content": "Get Started",
            "href": "https://app.example.com/dashboard",
            "locales": {
              "es": {
                "content": "Comenzar",
                "href": "https://app.example.com/es/dashboard"
              },
              "fr": {
                "content": "Commencer",
                "href": "https://app.example.com/fr/dashboard"
              }
            }
          }
        ]
      }
    }
  }'

require "courier"

courier = Courier::Client.new(api_key: ENV["COURIER_API_KEY"])

response = courier.send_.message(
  message: {
    to: {
      email: "sarah@acme-corp.com",
      locale: "es"
    },
    data: {
      user_name: "María"
    },
    content: {
      version: "2022-01-01",
      elements: [
        {
          type: "meta",
          title: "Welcome to our platform",
          locales: {
            es: { title: "Bienvenido a nuestra plataforma" },
            fr: { title: "Bienvenue sur notre plateforme" }
          }
        },
        {
          type: "text",
          content: "Thanks for signing up, {{user_name}}!",
          locales: {
            es: { content: "¡Gracias por registrarte, {{user_name}}!" },
            fr: { content: "Merci de vous être inscrit, {{user_name}} !" }
          }
        },
        {
          type: "action",
          content: "Get Started",
          href: "https://app.example.com/dashboard",
          locales: {
            es: {
              content: "Comenzar",
              href: "https://app.example.com/es/dashboard"
            },
            fr: {
              content: "Commencer",
              href: "https://app.example.com/fr/dashboard"
            }
          }
        }
      ]
    }
  }
)

puts("Sent with request ID: #{response.request_id}")

// Elemental nodes carry no typed content fields, so pass the document as raw JSON.
content := param.Override[shared.ElementalContentParam](json.RawMessage(`{
  "version": "2022-01-01",
  "elements": [
    {
      "type": "meta",
      "title": "Welcome to our platform",
      "locales": {
        "es": { "title": "Bienvenido a nuestra plataforma" },
        "fr": { "title": "Bienvenue sur notre plateforme" }
      }
    },
    {
      "type": "text",
      "content": "Thanks for signing up, {{user_name}}!",
      "locales": {
        "es": { "content": "¡Gracias por registrarte, {{user_name}}!" },
        "fr": { "content": "Merci de vous être inscrit, {{user_name}} !" }
      }
    },
    {
      "type": "action",
      "content": "Get Started",
      "href": "https://app.example.com/dashboard",
      "locales": {
        "es": {
          "content": "Comenzar",
          "href": "https://app.example.com/es/dashboard"
        },
        "fr": {
          "content": "Commencer",
          "href": "https://app.example.com/fr/dashboard"
        }
      }
    }
  ]
}`))

response, err := client.Send.Message(context.TODO(), courier.SendMessageParams{
	Message: courier.SendMessageParamsMessage{
		To: courier.SendMessageParamsMessageToUnion{
			OfUserRecipient: &shared.UserRecipientParam{
				Email:  courier.String("sarah@acme-corp.com"),
				Locale: courier.String("es"),
			},
		},
		Data: map[string]any{
			"user_name": "María",
		},
		Content: courier.SendMessageParamsMessageContentUnion{OfElementalContent: &content},
	},
})
if err != nil {
	panic(err.Error())
}

fmt.Printf("Sent with request ID: %s\n", response.RequestID)

SendMessageParams params = SendMessageParams.builder()
    .message(SendMessageParams.Message.builder()
        .to(UserRecipient.builder()
            .email("sarah@acme-corp.com")
            .locale("es")
            .build())
        .data(JsonValue.from(java.util.Map.of("user_name", "María")))
        // Elemental nodes carry no typed content fields, so pass the document as raw JSON.
        .content(JsonValue.from(java.util.Map.of(
            "version", "2022-01-01",
            "elements", java.util.List.of(
              java.util.Map.of(
                "type", "meta",
                "title", "Welcome to our platform",
                "locales", java.util.Map.of(
                  "es", java.util.Map.of("title", "Bienvenido a nuestra plataforma"),
                  "fr", java.util.Map.of("title", "Bienvenue sur notre plateforme"))),
              java.util.Map.of(
                "type", "text",
                "content", "Thanks for signing up, {{user_name}}!",
                "locales", java.util.Map.of(
                  "es", java.util.Map.of("content", "¡Gracias por registrarte, {{user_name}}!"),
                  "fr", java.util.Map.of("content", "Merci de vous être inscrit, {{user_name}} !"))),
              java.util.Map.of(
                "type", "action",
                "content", "Get Started",
                "href", "https://app.example.com/dashboard",
                "locales", java.util.Map.of(
                  "es", java.util.Map.of(
                    "content", "Comenzar",
                    "href", "https://app.example.com/es/dashboard"),
                  "fr", java.util.Map.of(
                    "content", "Commencer",
                    "href", "https://app.example.com/fr/dashboard")))))))
        .build())
    .build();
SendMessageResponse response = client.send().message(params);

$response = $client->send->message(
  message: [
    'to' => [
      'email' => 'sarah@acme-corp.com',
      'locale' => 'es',
    ],
    'data' => [
      'user_name' => 'María',
    ],
    'content' => [
      'version' => '2022-01-01',
      'elements' => [
        [
          'type' => 'meta',
          'title' => 'Welcome to our platform',
          'locales' => [
            'es' => ['title' => 'Bienvenido a nuestra plataforma'],
            'fr' => ['title' => 'Bienvenue sur notre plateforme'],
          ],
        ],
        [
          'type' => 'text',
          'content' => 'Thanks for signing up, {{user_name}}!',
          'locales' => [
            'es' => ['content' => '¡Gracias por registrarte, {{user_name}}!'],
            'fr' => ['content' => 'Merci de vous être inscrit, {{user_name}} !'],
          ],
        ],
        [
          'type' => 'action',
          'content' => 'Get Started',
          'href' => 'https://app.example.com/dashboard',
          'locales' => [
            'es' => [
              'content' => 'Comenzar',
              'href' => 'https://app.example.com/es/dashboard',
            ],
            'fr' => [
              'content' => 'Commencer',
              'href' => 'https://app.example.com/fr/dashboard',
            ],
          ],
        ],
      ],
    ],
  ],
);

SendMessageParams parameters = new()
{
    Message = new()
    {
        To = new UserRecipient { Email = "sarah@acme-corp.com", Locale = "es" },
        Data = new Dictionary<string, JsonElement>()
        {
            { "user_name", JsonSerializer.SerializeToElement("María") },
        },
        // Elemental nodes expose no typed content fields, so build the document from raw JSON.
        Content = ElementalContent.FromRawUnchecked(
            JsonSerializer.Deserialize<Dictionary<string, JsonElement>>("""
            {
              "version": "2022-01-01",
              "elements": [
                {
                  "type": "meta",
                  "title": "Welcome to our platform",
                  "locales": {
                    "es": { "title": "Bienvenido a nuestra plataforma" },
                    "fr": { "title": "Bienvenue sur notre plateforme" }
                  }
                },
                {
                  "type": "text",
                  "content": "Thanks for signing up, {{user_name}}!",
                  "locales": {
                    "es": { "content": "¡Gracias por registrarte, {{user_name}}!" },
                    "fr": { "content": "Merci de vous être inscrit, {{user_name}} !" }
                  }
                },
                {
                  "type": "action",
                  "content": "Get Started",
                  "href": "https://app.example.com/dashboard",
                  "locales": {
                    "es": {
                      "content": "Comenzar",
                      "href": "https://app.example.com/es/dashboard"
                    },
                    "fr": {
                      "content": "Commencer",
                      "href": "https://app.example.com/fr/dashboard"
                    }
                  }
                }
              ]
            }
            """)),
    },
};

var response = await client.Send.Message(parameters);

courier send message \
  --api-key "$COURIER_API_KEY" \
  --message.to '{"email": "sarah@acme-corp.com", "locale": "es"}' \
  --message.data '{"user_name": "María"}' \
  --message.content '{"version": "2022-01-01", "elements": [{"type": "meta", "title": "Welcome to our platform", "locales": {"es": {"title": "Bienvenido a nuestra plataforma"}, "fr": {"title": "Bienvenue sur notre plateforme"}}}, {"type": "text", "content": "Thanks for signing up, {{user_name}}!", "locales": {"es": {"content": "¡Gracias por registrarte, {{user_name}}!"}, "fr": {"content": "Merci de vous être inscrit, {{user_name}} !"}}}, {"type": "action", "content": "Get Started", "href": "https://app.example.com/dashboard", "locales": {"es": {"content": "Comenzar", "href": "https://app.example.com/es/dashboard"}, "fr": {"content": "Commencer", "href": "https://app.example.com/fr/dashboard"}}}]}'

With Courier MCP, send a localized email to sarah@acme-corp.com in Spanish, translating the title, body, and button.

The example covers:

Meta element: Localizing the email subject line (title property)
Text element: Localizing body content with Handlebars variables
Action element: Localizing both button text (content) and URL (href)

Structured elements

When a text node uses the elements array (inline string, link, and img nodes), provide locale translations as elements arrays too. That preserves bold, italic, and inline links across languages.

{
  "type": "text",
  "elements": [
    { "type": "string", "content": "Your order " },
    { "type": "string", "content": "#{{order.id}}", "bold": true },
    { "type": "string", "content": " has been " },
    { "type": "string", "content": "confirmed", "bold": true },
    { "type": "string", "content": "." }
  ],
  "locales": {
    "fr": {
      "elements": [
        { "type": "string", "content": "Votre commande " },
        { "type": "string", "content": "#{{order.id}}", "bold": true },
        { "type": "string", "content": " a été " },
        { "type": "string", "content": "confirmée", "bold": true },
        { "type": "string", "content": "." }
      ]
    },
    "ja": {
      "elements": [
        { "type": "string", "content": "ご注文 " },
        { "type": "string", "content": "#{{order.id}}", "bold": true },
        { "type": "string", "content": " が" },
        { "type": "string", "content": "確認", "bold": true },
        { "type": "string", "content": "されました。" }
      ]
    }
  }
}

Mixed locale formats

You can mix content and elements across locales in the same text node. Use it when some translations need formatting and others can be plain strings:

{
  "type": "text",
  "elements": [
    { "type": "string", "content": "Need help? " },
    { "type": "link", "content": "Contact support", "href": "https://support.example.com" },
    { "type": "string", "content": "." }
  ],
  "locales": {
    "fr": {
      "content": "Besoin d'aide ? [Contacter le support](https://support.example.com/fr)."
    },
    "es": {
      "elements": [
        { "type": "string", "content": "¿Necesita ayuda? " },
        { "type": "link", "content": "Contactar soporte", "href": "https://support.example.com/es" },
        { "type": "string", "content": "." }
      ]
    }
  }
}

The French locale uses a content string, which Courier wraps into a single text element at render time. The Spanish locale keeps the structured elements with an inline link.

When Both `content` and `elements` Are Present

If a locale entry includes both content and elements, only elements is used. Choose one format per locale entry. See the resolution table for all combinations.

Locale sources

Courier resolves the recipient’s locale in this order:

message.to.locale: Set in the to object of the send request (highest priority)
User profile locale: Stored in the user’s profile via the
Default fallback: If no locale is found, the default content is used

message.to.locale takes precedence over every other source. Courier merges it into the profile object during processing, so it overrides any locale stored in the user’s profile.

Two places to set it:

// Option 1: In message.to.locale (highest priority)
await courier.send.message({
  message: {
    to: {
      email: "sarah@acme-corp.com",
      locale: "fr",
    },
    content: { ... },
  },
});

// Option 2: On the user's stored profile, so every send picks it up
await courier.profiles.create("user_123", {
  profile: { locale: "fr" },
});

await courier.send.message({
  message: {
    to: {
      user_id: "user_123",
    },
    content: { ... },
  },
});

# Option 1: In message.to.locale (highest priority)
client.send.message(
    message={
        "to": {
            "email": "sarah@acme-corp.com",
            "locale": "fr",
        },
        "content": { ... },
    }
)

# Option 2: On the user's stored profile, so every send picks it up
client.profiles.create("user_123", profile={"locale": "fr"})

client.send.message(
    message={
        "to": {
            "user_id": "user_123",
        },
        "content": { ... },
    }
)

# Option 1: In message.to.locale (highest priority)
curl -X POST https://api.courier.com/send \
  -H "Authorization: Bearer $COURIER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "message": {
      "to": { "email": "sarah@acme-corp.com", "locale": "fr" },
      "content": { ... }
    }
  }'

# Option 2: On the user's stored profile, so every send picks it up
curl -X POST https://api.courier.com/profiles/user_123 \
  -H "Authorization: Bearer $COURIER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "profile": { "locale": "fr" } }'

curl -X POST https://api.courier.com/send \
  -H "Authorization: Bearer $COURIER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "message": {
      "to": { "user_id": "user_123" },
      "content": { ... }
    }
  }'

# Option 1: In message.to.locale (highest priority)
courier.send_.message(
  message: {
    to: {
      email: "sarah@acme-corp.com",
      locale: "fr"
    },
    content: { ... }
  }
)

# Option 2: On the user's stored profile, so every send picks it up
courier.profiles.create("user_123", profile: { locale: "fr" })

courier.send_.message(
  message: {
    to: {
      user_id: "user_123"
    },
    content: { ... }
  }
)

// `content` is the Elemental document, built as raw JSON in the examples above.

// Option 1: In message.to.locale (highest priority)
client.Send.Message(context.TODO(), courier.SendMessageParams{
	Message: courier.SendMessageParamsMessage{
		To: courier.SendMessageParamsMessageToUnion{
			OfUserRecipient: &shared.UserRecipientParam{
				Email:  courier.String("sarah@acme-corp.com"),
				Locale: courier.String("fr"),
			},
		},
		Content: courier.SendMessageParamsMessageContentUnion{OfElementalContent: &content},
	},
})

// Option 2: On the user's stored profile, so every send picks it up
client.Profiles.New(context.TODO(), "user_123", courier.ProfileNewParams{
	Profile: map[string]any{"locale": "fr"},
})

client.Send.Message(context.TODO(), courier.SendMessageParams{
	Message: courier.SendMessageParamsMessage{
		To: courier.SendMessageParamsMessageToUnion{
			OfUserRecipient: &shared.UserRecipientParam{
				UserID: courier.String("user_123"),
			},
		},
		Content: courier.SendMessageParamsMessageContentUnion{OfElementalContent: &content},
	},
})

// `content` is the Elemental document, built as raw JSON in the examples above.

// Option 1: In message.to.locale (highest priority)
client.send().message(SendMessageParams.builder()
    .message(SendMessageParams.Message.builder()
        .to(UserRecipient.builder()
            .email("sarah@acme-corp.com")
            .locale("fr")
            .build())
        .content(content)
        .build())
    .build());

// Option 2: On the user's stored profile, so every send picks it up
client.profiles().create(ProfileCreateParams.builder()
    .userId("user_123")
    .profile(ProfileCreateParams.Profile.builder()
        .putAdditionalProperty("locale", JsonValue.from("fr"))
        .build())
    .build());

client.send().message(SendMessageParams.builder()
    .message(SendMessageParams.Message.builder()
        .to(UserRecipient.builder().userId("user_123").build())
        .content(content)
        .build())
    .build());

// $content is the Elemental document, built as an array in the examples above.

// Option 1: In message.to.locale (highest priority)
$client->send->message(
  message: [
    'to' => ['email' => 'sarah@acme-corp.com', 'locale' => 'fr'],
    'content' => $content,
  ],
);

// Option 2: On the user's stored profile, so every send picks it up
$client->profiles->create('user_123', profile: ['locale' => 'fr']);

$client->send->message(
  message: [
    'to' => ['userID' => 'user_123'],
    'content' => $content,
  ],
);

// `content` is the Elemental document, built from raw JSON in the examples above.

// Option 1: In message.to.locale (highest priority)
await client.Send.Message(new SendMessageParams
{
    Message = new()
    {
        To = new UserRecipient { Email = "sarah@acme-corp.com", Locale = "fr" },
        Content = content,
    },
});

// Option 2: On the user's stored profile, so every send picks it up
await client.Profiles.Create(new ProfileCreateParams
{
    UserID = "user_123",
    Profile = new Dictionary<string, JsonElement>()
    {
        { "locale", JsonSerializer.SerializeToElement("fr") },
    },
});

await client.Send.Message(new SendMessageParams
{
    Message = new()
    {
        To = new UserRecipient { UserID = "user_123" },
        Content = content,
    },
});

# CONTENT holds the Elemental document, as in the examples above.

# Option 1: In message.to.locale (highest priority)
courier send message \
  --api-key "$COURIER_API_KEY" \
  --message.to '{"email": "sarah@acme-corp.com", "locale": "fr"}' \
  --message.content "$CONTENT"

# Option 2: On the user's stored profile, so every send picks it up
courier profiles create \
  --api-key "$COURIER_API_KEY" \
  --user-id user_123 \
  --profile '{"locale": "fr"}'

courier send message \
  --api-key "$COURIER_API_KEY" \
  --message.to '{"user_id": "user_123"}' \
  --message.content "$CONTENT"

With Courier MCP, send my greeting to sarah@acme-corp.com and set the locale to fr on the message." Use the Courier MCP tool "create_or_merge_user" with a prompt like: "Store the locale fr on user_123's profile so their sends localize.

Set the locale in the user’s profile (via the Profiles API) and every notification for that user is localized, with no locale in the send request. message.to.locale still overrides it.

Best practices

Use consistent locale codes

Use standard locale codes (en-US, es-ES, fr-FR) or simple language codes (en, es, fr) consistently across your templates. Courier supports any locale string format, but consistency makes maintenance easier.

Provide default content

Always provide default content for each element. Notifications then render even when:

A user’s locale isn’t supported
A translation is missing
The locale field is omitted

Localize URLs when needed

For action buttons and images, localize the href and src properties to point at localized versions of your website or app:

{
  "type": "action",
  "content": "View Dashboard",
  "href": "https://app.example.com/dashboard",
  "locales": {
    "es": {
      "content": "Ver Panel",
      "href": "https://app.example.com/es/dashboard"
    }
  }
}

Combine with channel customization

Combine locales with for localized, per-channel content:

{
  "type": "channel",
  "channel": "email",
  "elements": [
    {
      "type": "text",
      "content": "Check your email for details",
      "locales": {
        "es": {
          "content": "Revisa tu correo para más detalles"
        }
      }
    }
  ]
}

Test all locales

Before deploying, test your templates with every supported locale and check:

All translations are present
Handlebars variables work correctly in all languages
URLs and links are properly localized
Text fits within UI constraints (button sizes, email widths, etc.)

Get started

Send messages

Journeys

Broadcasts

Design

Recipients

Tenants

Monitoring

Workspaces

Resources

Template translations

How it works

Text node resolution

Why use locales

Supported elements and properties

Add translations

Workspace translation strings

Basic example

Localizing multiple elements

Structured elements

Mixed locale formats

When Both `content` and `elements` Are Present

Locale sources

Best practices

Use consistent locale codes

Provide default content

Localize URLs when needed

Combine with channel customization

Test all locales

​How it works

​Text node resolution

​Why use locales

​Supported elements and properties

​Add translations

​Workspace translation strings

​Basic example

​Localizing multiple elements

​Structured elements

​Mixed locale formats

​When Both content and elements Are Present

​Locale sources

​Best practices

​Use consistent locale codes

​Provide default content

​Localize URLs when needed

​Combine with channel customization

​Test all locales

How it works

Text node resolution

Why use locales

Supported elements and properties

Add translations

Workspace translation strings

Basic example

Localizing multiple elements

Structured elements

Mixed locale formats

When Both `content` and `elements` Are Present

Locale sources

Best practices

Use consistent locale codes

Provide default content

Localize URLs when needed

Combine with channel customization

Test all locales