Texts

Every text the chat shows has a key, such as composer.placeholder. The library ships each text in English and Polish, and you can replace any of them per bot. The keys are public API (ADR-0006), so you can rely on them in your configuration.

The keys cover the chat and the launcher on your page: launcher.*, and header.title, which also names the chat dialog. A key named after an error code, such as error.rate_limited, is the text the widget shows for that code; some errors have a more specific key, such as error.conversationTooLong. The server sends these keys with its errors (Wire protocol).

Override texts

Set widget.texts in defineBot:

defineBot({
  // …
  widget: {
    texts: {
      'composer.placeholder': 'Ask about plans, support or security…',
      'launcher.label': 'Questions?',
      'message.attachments.one': '{count} file',
      'message.attachments.other': '{count} files',
    },
  },
});

• Keys. Only the keys in the table below are accepted. An unknown key, or a text that is empty or longer than 300 characters, makes defineBot throw at startup.
• Shortcuts. title, greeting, placeholder and launcherLabel set header.title, welcome.greeting, composer.placeholder and launcher.label. If you set a shortcut and the same key in texts, the shortcut wins.
• Every language. An override replaces the text in every language. With locale: 'auto', Polish visitors see your override too.
• Placeholders. Words in braces, such as {count}, {name}, {size} and {max}, are filled in by the widget. Keep the ones the default text has. A placeholder the widget doesn't fill for that key is shown as typed.
• Bold. In welcome.greeting, **words** are shown in bold.

A page can still set its own greeting with askdare('configure', { greeting }); see Styling.

Languages

widget.locale picks the language:

defineBot throws on a value that is neither 'auto' nor a valid BCP 47 tag. The language part of the tag picks the dictionary, and the full tag picks the plural rules.

With 'auto', the launcher on your page follows the same order. Your instructions function receives the chosen tag as context.locale, so you can tell the model which language to answer in.

Plurals

A text with a number has one key per plural category: zero, one, two, few, many and other, the categories Intl.PluralRules uses. message.attachments is such a text: after a page reload, the chat shows it under each message that had files.

The widget asks Intl.PluralRules which category the number falls into for the visitor's locale and shows the text for it. When the language has no text for that category, the widget shows the other text.

Each language uses only some categories:

• English uses one and other. Zero is other in English, so message.attachments.zero has no effect there.
• Polish uses one, few, many and other (fractions): 1 załącznik, 3 załączniki, 5 załączników.

To see the categories of another language, run new Intl.PluralRules('cs').resolvedOptions().pluralCategories in a browser console. Override every category the language uses: if you set only one and other on a Polish bot, few and many keep their Polish defaults.

Add a language

The library has dictionaries for English and Polish only, and widget.texts has no per-language form. For another language, set a fixed locale and translate every key:

defineBot({
  // …
  widget: {
    locale: 'de',
    texts: {
      'header.title': 'Assistent',
      'composer.placeholder': 'Nachricht eingeben…',
      'message.attachments.one': '{count} Anhang',
      'message.attachments.other': '{count} Anhänge',
      // … and every other key
    },
  },
});

• Keys you leave out show English.
• Plurals follow the rules of the tag you set, so translate each category the language uses.
• Keep locale fixed. With 'auto', your translations would show to every visitor, whatever their language. For a site in several languages without a dictionary, define one bot per language, each with its own locale and texts.
• The chat document's lang attribute is your locale as soon as widget.texts has any key, so screen readers read your translation in the right language. Without your texts, a language without a built-in dictionary shows English, and lang says en.

All texts

The table is generated from the library's dictionaries with pnpm --filter @boldare/askdare docs:texts.

A dash (—) means the language has no text of its own for that plural category, so the widget shows the other text.