Skip to main content

Multilingual Messaging

Each eCourtDate client has a preferred language. eCourtDate uses it to select the template for each flow message, auto message, and bulk action that goes to the client. An integration sets the preferred language when it creates or updates clients, through the REST API or through SFTP file uploads. Everything else in the workflow is the same for both methods.

eCourtDate does not translate a message at send time. It sends the template in the preferred language of the client. When there is no template in that language, it sends the English template.

Setup Overview​

The agency configuration in Part 1 must be complete before the integration sends a preferred language in Part 2.

StepWhereWho
1. Enable languagesAgency app, Admin > SettingsAgency admin
2. Turn on Detect LanguageAgency app, Admin > SettingsAgency admin
3. Add templates in each languageAgency app: Flows, Auto Messages, Bulk Actions, Agency Phones, PortalsAgency admin
4a. Send the preferred language through the APIThe integrationIntegration developer
4b. Send the preferred language through SFTPUpload Template in the Agency app, and the export fileIntegration developer, with the agency admin
5. VerifyAgency app and APIIntegration developer, with the agency

Do Step 4a or Step 4b. An agency that uses both methods does both.

Before Starting​

Agency app access. Steps 1 to 3 need a user who can edit settings, flows, auto messages, bulk actions, agency phones, and portals in the eCourtDate Agency app (staging or production).

API credentials. Step 4a needs API credentials for the agency. See Authentication.

SFTP Profile. Step 4b needs an SFTP Profile with an Upload Template. See Server Setup.

The list of languages. Agree with the agency on the languages that its clients use. Find the code of each language in Language Codes.

Staging first. Do all steps in the staging agency first. Then repeat them in the production agency.

Part 1: Agency Configuration​

Step 1: Enable Languages​

The enabled languages are the languages that the agency writes templates in. The template editors show a language only after the agency enables it.

  1. In the Agency app, click Admin > Settings.
  2. Go to the Languages section.
  3. In Languages, select each language that the agency uses.
    • Add All selects all supported languages.
    • Set Default selects English and Spanish.
    • Reset clears the list.
  4. Click Save.

Default Language sets the first language of a new post. It does not set the preferred language of clients or the language of messages.

When the agency enables no languages, the template editors show Choose enabled languages in General Settings or No languages enabled. Choose languages in General Settings. General Settings is the Admin > Settings page.

Step 2: Turn On Detect Language​

Detect Language finds the language of each text message that a client sends to the agency. It then changes the preferred language of the client to that language. See Detect Language for Inbound Messages for the full rules.

  1. In the Agency app, click Admin > Settings.
  2. Go to the Automation section.
  3. Select Detect Language. The help text is "Automatically detect the language of incoming messages and update the client's preferred language."
  4. Click Save.

Detect Language is on by default in new agencies.

Detect Language and Integration Updates

Detect Language and the integration both write the preferred language. The next API update or SFTP row with a preferred language replaces the language that Detect Language set. If the source system holds the correct language, keep it current there. If clients choose their language by text, send the preferred language only when the integration creates the client.

Step 3: Add Templates in Each Language​

A message goes out in the preferred language of the client only when a template exists in that language. Add a template in each enabled language to each flow, auto message, and bulk action that clients get.

The Auto Translate buttons fill a template by machine translation of the English template. They keep the square brackets of merge tags. Read each translation before the agency sends it. Make sure that each merge tag has the same name as in the English template. The editors show Unknown tags: under a template that has a tag name that is not correct. For the merge tag rules, see Templates in More Than One Language.

Flows​

  1. In the Agency app, open Flows and open the flow.
  2. Write the English Subject Line and Message Body for each message in the flow.
  3. Click Auto Translate All Languages to fill all languages. Or click Auto Translate in one language block, such as Español (spanish) Message, to fill only that language.
  4. Read each translation and correct it.
  5. Click Save. Auto Translate does not save the flow.

The flow drops an empty template in a language other than English when the agency saves it.

Auto Messages​

  1. In the Agency app, open Auto Messages and open the auto message.
  2. Write the English subject and template.
  3. Click Show Languages.
  4. Click Auto Translate All to fill all languages. Or click Auto Translate {Language}, such as Auto Translate Español (spanish), to fill only that language.
  5. Read each translation and correct it.

Auto Translate saves the auto message after it fills the template.

Bulk Actions​

  1. In the Agency app, open Bulk Actions and open a bulk action of the Send a Message type.
  2. Write the English subject and message. A bulk action needs an English message.
  3. Click Translate in the toolbar to fill all languages that have no message. If all languages have a message, the Agency app asks to overwrite them from English.
  4. To fill one language, open the tab of that language and click Auto Translate.
  5. Read each translation and correct it, then save the bulk action.

Agency Phones​

The auto responses of an agency phone have one version for each language.

  1. In the Agency app, open Agency Phones and open the phone.
  2. Write the English Inbound Texts Auto Response, Inbound Calls Auto Response, and Inbound Calls Response.
  3. Select a different language in the language menu, then click Auto Translate.
  4. Read the translation and correct it.
  5. Click Save.

eCourtDate selects the Inbound Texts Auto Response in the language that Detect Language finds in the inbound text. When there is no response in that language, or Detect Language is off, it sends the English response.

Portals​

  1. In the Agency app, open Portals and open the portal.
  2. Switch to each language and write the multilingual content of the portal.
  3. Under Welcome Info (multilingual), click Auto Translate to fill the welcome text from English. The other portal fields have no Auto Translate button.

A portal opens in the preferred language of the client when the client follows a link from a message, if the agency enables that language.

Part 2: Send the Preferred Language​

Step 4a: Send the Preferred Language through the API​

The language field of the client object holds the preferred language.

Value rules:

  • Send the language code from Language Codes, in lowercase. For example, send es for Spanish.
  • Send a code that the agency enabled in Step 1.
  • Do not send a region, such as es-MX. eCourtDate selects a template only on an exact match of the code. A client with es-MX gets the English template, also when the flow has a Spanish template.
  • Do not send a language name, such as Spanish. The API stores the value exactly as sent and does not change or validate it.
  • When language is not in a create request, the preferred language is en.

Get the Enabled Languages​

GET /v1/languages

Returns the languages that the agency enabled in Step 1. The API client needs permission to view agency settings. Use this list to map the codes of the source system to eCourtDate codes.

[
  {"key": "en", "label": "English"},
  {"key": "es", "label": "Español (spanish)"},
  {"key": "vi", "label": "Tiếng việt (vietnamese)"}
]

The response is an empty array when the agency enabled no languages. An entry can also be a code only, such as "es", in agencies that set their languages before the {key, label} format.

Create a Client with a Preferred Language​

curl -X POST "$BASE_URL/v1/clients" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "client_reference": "CMS-100245",
    "first_name": "Alex",
    "last_name": "Rivera",
    "language": "es"
  }'

Change the Preferred Language​

curl -X PATCH "$BASE_URL/v1/clients/CMS-100245" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"language": "vi"}'

The path value is the client UUID or the client_reference. When the preferred language changes, eCourtDate rebuilds the unsent flow messages of the client's events that are today or later, and the messages of the client's payments. The rebuilt messages use the template in the new language.

  • Scheduled auto messages and scheduled one-off messages keep their language. eCourtDate does not rebuild them.
  • skip_sync: true stops the rebuild. The flow messages that are already scheduled then keep the old language.

See Update a Client.

Messages Sent through the API​

Each message endpoint selects the language in a different way.

EndpointLanguage of the message
POST /v1/messages (one-off)The language field of the request. When the request has no language, the language is en. eCourtDate does not use the preferred language of an attached client. Write content in the language of the client, then send language with the same code.
POST /v1/messages/bulksThe language field of each item in the messages array. When an item has no language, the language is en.
POST /v1/auto_messages/{uuid}/sendWith a client, the template in the preferred language of the client. Without a client, the template in the language field of the request. When there is no template in that language, the English template.

eCourtDate does not translate the content of a one-off or bulk message. The language field sets the language of date and time merge tags in the content. See Languages and Translation.

Step 4b: Send the Preferred Language through SFTP​

The Preferred Language field of an Upload Template holds the preferred language. Its field key is clients.language.

Map the Column​

  1. In the Agency app, open Upload Templates and open the template that the SFTP Profile uses.
  2. In Field Mapping, find Preferred Language (marked Client).
  3. Enter the column header of the language column, exactly as it is in the file. Header matching is case-sensitive. If the template maps by column position, enter the column number.
  4. Save the template.

The Upload Template has no default value for the preferred language.

Value Rules​

An SFTP file can hold the code or the name of the language. eCourtDate stores the code. For example, es, ES, es-MX, spa, Spanish, and Español all set es.

  • Use the code from Language Codes when the source system has one. The code is the same value that the API uses.
  • eCourtDate also accepts a locale, an ISO 639-2 code, and the names of each language. See SFTP Value Rules.
  • eCourtDate ignores case and the spaces at the start and end of the value.
  • eCourtDate stores en for all other values, such as N/A, Unknown, or a code that eCourtDate does not support.
  • A blank cell does not change the preferred language of an existing client.

Example file with a pipe delimiter:

ClientID|FirstName|LastName|Phone|PreferredLanguage
CMS-100245|Alex|Rivera|5551234567|Spanish
CMS-100246|Sam|Nguyen|5559876543|vi
CMS-100247|Jordan|Lee|5555550123|eng
CMS-100248|Casey|Morales|5555550188|es-MX

In this file, the Preferred Language mapping is PreferredLanguage. The four clients get es, vi, en, and es.

An SFTP row with a preferred language replaces the preferred language of an existing client. This includes a language that Detect Language set.

Step 5: Verify​

  1. Create or update a test client with a preferred language other than English, through the API or a test SFTP file.
  2. In the Agency app, open the client. Make sure that Preferred Language shows the correct language.
  3. Make sure that each flow, auto message, and bulk action has a template in that language. In the Agency app, the Preview page shows {Language} translation not available when a template in that language is missing.
  4. Create a test event for the client. Make sure that the scheduled messages have the template in the correct language.
  5. Through the API, list the clients in one language: GET /v1/clients?language=es.
  6. Through the API, list the language values that the clients have: GET /v1/client_languages. The response shows the distinct values of the clients that were created in the last 12 months and are not archived or deleted, for example [{"language": "en"}, {"language": "es"}]. An unexpected value, such as es-MX or Spanish, shows a mapping error in the integration.

Detect Language for Inbound Messages​

When Detect Language is on, eCourtDate checks each text message that a client sends to an agency phone.

  1. Keyword check. When the full text of the message is a language keyword, eCourtDate uses that language. For example, español or castellano sets Spanish, and english sets English. The check ignores the case of the letters A to Z. The keywords are in the Inbound keywords column of Language Codes.
  2. Machine detection. For all other messages, eCourtDate detects the language of the text by machine. It uses the result only when the confidence score is above 0.9. When no result is above 0.9, the message has no detected language.
  3. Message language. eCourtDate stores the detected code as the language of the inbound message.
  4. Client update. eCourtDate changes the preferred language of the client to the detected language when all of these are true:
    • The phone number of the sender matches a text contact of a client.
    • The client is not archived or deleted.
    • The client has a preferred language.
    • The detected language is different from the preferred language of the client.
  5. Rebuild. eCourtDate rebuilds the unsent flow messages of the client's events that are today or later, and the messages of the client's payments, in the new language.
  6. Confirmation. When the agency enabled the detected language, eCourtDate sends this text in English: Your preferred language has been changed to {label}. The {label} is the label of the language in Admin > Settings, such as Español (spanish). When the new language is not English, the text also has Reply ENGLISH to change back.

Detect Language also has these rules:

  • It checks all inbound text messages. This includes opt-out keywords such as STOP. There is no minimum length.
  • It changes the preferred language also when the agency did not enable the detected language. In that case, eCourtDate sends no confirmation, and the client gets the English templates.
  • It checks text messages only. It does not check email or voice.
  • When Detect Language is off, the language keywords do not change the preferred language.

Read an inbound message in English. On an inbound message in a language other than English, the Agency app shows an Auto Translate button. It shows a machine translation into English above the original text. It does not save the translation.

Other Ways the Preferred Language Changes​

The integration is not the only source of the preferred language. These actions also change it:

SourceChange
Detect LanguageSets the language of an inbound text, as described in Detect Language for Inbound Messages.
Agency appAn agency user changes Preferred Language on the client.
Portal profileThe client changes the language in the profile of a portal.
Portal sign-upA client that a portal page creates gets the language of that page.

The next API update or SFTP row with a preferred language replaces each of these changes.

Auto Translate Features​

All Auto Translate features use machine translation. eCourtDate does not translate messages at send time. Each feature fills text only when an agency user clicks it.

WhereButtonTranslatesSaves
FlowsAuto Translate, Auto Translate All LanguagesEnglish subject and body to one language or to all languagesNo. Click Save.
Auto MessagesAuto Translate {Language}, Auto Translate AllEnglish subject and template to one language or to all languagesYes
Bulk ActionsAuto Translate, TranslateEnglish subject and message to one language, or to all languages that have no messageNo. Save the bulk action.
Agency PhonesAuto TranslateEnglish auto responses to the selected languageNo. Click Save.
PortalsAuto TranslateEnglish Welcome Info to the current languageYes
Send a Message (client and event records)Auto TranslateThe message to the preferred language of the client, or to a selected language. Also sets the language of the message.Not applicable. The user sends the message.
Check-insAuto TranslateThe message to a selected languageNot applicable. The user sends the message.
Contact recordsAuto TranslateAdds a translation after the message text, with the label (AUTO-TRANSLATION)Not applicable. The user sends the message.
PostsAuto translate from {Language} in Translate toolsTitle, summary, and description from the language of the postNo. Save the post.
Design StudioAuto TranslateThe fields of the design from the primary language. Locked fields stay as written.No. Save the design.
Inbound messagesAuto TranslateThe inbound message to English, for display onlyNo

FAQs​

Why does a client with Spanish as the preferred language get a message in English?

The flow, auto message, or bulk action has no Spanish template, so eCourtDate sends the English template. Or the API stored a value that is not exactly es, such as es-MX or Spanish. Add a Spanish template, and send es through the API.

Why do all clients from an SFTP file get English?

The Preferred Language mapping does not match the column header, or the column holds values that eCourtDate does not accept, such as N/A. Header matching is case-sensitive. See Value Rules.

Does eCourtDate translate a message when a template is missing?

No. eCourtDate sends the English template. Auto Translate fills templates only when an agency user clicks it.

Does a preferred language change move messages that are already scheduled?

Yes for flow messages of events that are today or later, and for payment messages. No for scheduled auto messages and one-off messages. An API update with skip_sync: true does not rebuild any messages.

Can a client change the preferred language by text?

Yes, when Detect Language is on. The client texts a language keyword, such as español, as the full message. See Detect Language for Inbound Messages.

Are merge tag values translated?

No. Only date and time values and some words in the Schedule and business tags change with the language of the template. See Languages and Translation.

Need help? Open a support ticket in the Console using the Help button in the bottom-right corner.