Text customization

Text Customization Documentation

This guide explains how to customize the text displayed across widgets globally and for specific widget instances. Text customization supports multi-language configurations and placeholders for dynamic content.

Overview of Text Customization

Global Text Customization Modify the default text used across all widgets globally.
Widget-Specific Text Customization Customize the text for individual widget instances. For example, you can configure the text of a button differently in two separate widgets.

Note: Widgets are language-aware, so custom texts must be provided for each supported language.

Setting Up Text Customizations

To configure text customizations, use the textCustomizations object in your widget setup. This object maps customization keys to language-specific text values.

Example: Basic Text Customization

window.BilberryWidgetsGlobal.textCustomizations = {
    book_now: {
        en: 'Buy now',
        nb: 'Kjøp nå',
    },
    custom_button_text: {
        en: 'Custom Button',
        nb: 'Tilpasset knapp',
    },
};

Key: book_now (default key for global use).
Languages: en (English) and nb (Norwegian Bokmål).

Using Placeholders for Dynamic and Pluralized Text

The placeholder system enables dynamic content in text customizations, with support for runtime value replacement, pluralization, and conditional sentence selection. However, the correct format for each text key must be followed, as not all keys support placeholders.

Example: Basic Value Replacement

For simple dynamic value replacement, use placeholders in the template property. This method allows runtime values to be inserted directly into the text.

window.BilberryWidgetsGlobal.textCustomizations = {
    booking_is_closed: {
        en: {
            template: 'Booking for <NAME> is now closed',
        },
    },
};

Placeholder: <NAME> is replaced at runtime with a specific value, such as the name of an activity or product.
Output Example:
- If <NAME> = "Hiking Adventure", the text will read:
  - English: Booking for Hiking Adventure is now closed

Example: Pluralization Support

For cases requiring singular or plural adjustments, use the COUNT keyword with the format <COUNT:singular:plural>. The COUNT placeholder dynamically adjusts the text based on its numeric value.

window.BilberryWidgetsGlobal.textCustomizations = {
    participants_count: {
        en: { template: 'You have <COUNT:participant:participants>' },
        nb: { template: 'Du har <COUNT:deltaker:deltakere>' },
    },
};

Placeholder: <COUNT> determines whether the singular or plural form is used.
Output Examples:
- When <COUNT> = 1:
  - English: You have 1 participant
- When <COUNT> = 5:
  - English: You have 5 participants

Important: The keyword COUNT is mandatory for pluralization templates. Attempting to use other placeholders (e.g., <NUMBER>) in this format will not work.

Best Practices for Placeholders

Match Placeholders to Key Requirements Use template for runtime value replacement and ensure placeholders (e.g., <NAME>, <COUNT>) correspond to the data provided.
Reserve COUNT for Pluralization The COUNT keyword is exclusively used for singular/plural adjustments. Do not substitute other variable names in its place.
Consistency Across Languages Define placeholders and their replacements for all supported languages to ensure proper functionality in multilingual setups.
Test Placeholder Behavior Validate that runtime values replace placeholders as intended, and that singular/plural forms adjust correctly.

By following these guidelines, placeholders can create dynamic and grammatically accurate text across all use cases.

Global Text Customization

Global customization keys affect all widgets. Use the pre-defined keys to overwrite defaults globally. For instance:

window.BilberryWidgetsGlobal.textCustomizations = {
    show_cancellation_policy: { en: 'Show Policy', nb: 'Vis policy' },
    price: { en: 'Price', nb: 'Pris' },
};

Complete List of Global Customization Keys

Please refer to the Full list of global text keys for a comprehensive list of available keys.

You can specify unique text customizations for individual widgets by referencing the customization key in the widget’s attributes.

Example: Customizing a Button Text

<bilberry-booking-button
    button-text-customization-key="custom_button_text"
></bilberry-booking-button>

Here, the button-text-customization-key points to the custom_button_text key defined in the textCustomizations object.

Advanced Configurations

Using Functions for Pluralization or Dynamic Text

Some text keys support advanced configurations such as pluralization. For example:

window.BilberryWidgetsGlobal.textCustomizations = {
    travelers_count: {
        en: {
            template: 'You have <COUNT:traveler:travelers>',
        },
    },
};

traveler (singular) and travelers (plural) adjust dynamically based on <COUNT>.

Best Practices

Define Global Defaults First Start with global customization keys to ensure consistent language and tone across all widgets.
Use Descriptive Keys Use clear, descriptive names for custom keys, such as custom_button_text instead of btn_txt.
Keep Multi-Language Support in Mind Always define text values for all supported languages to avoid missing translations.
Utilize Placeholders Use placeholders like <COUNT> for dynamic values to reduce redundancy and improve maintainability.