Locales¶

Locales are JSON resources that provide localized content for different regions and languages, enhancing user experience and accessibility.

Attribute	Type	Required	Description	Default
`culture`	string	Yes	String with culture code	-
`locale`	Object	Yes	Object containing the locale structure	-
They allow you to efficiently manage and display information in various languages and regional formats.

{
  "culture": "en",
  "locale": {
      "sections": {
        "headers": {
          "welcomeMessage": "Welcome to Experience Builder!"
        },
        "buttons": {
          "submitButton": "Submit Order"
        }
      }
  }
}

Context Locales¶

Context locales are JSON resources that inherit and override one or more properties of the parent JSON locale to suit a specific context. By allowing targeted adjustments, context locales enable customization of language, formatting, or other locale-specific elements, ensuring that content is appropriately tailored to different environments or user needs without altering the parent configuration. A contextual locale has three attributes that determine the scope of its inheritance, defining how it inherits properties from the parent locale and customizes them for a specific context. These attributes allow for precise control over how the locale behaves, ensuring it aligns with the requirements of different environments or use cases while maintaining consistency with the parent configuration.

Attribute	Type	Required	Description	Default
`parent`	String	Yes	The parent JSON page to inherit from	-
`context`	Object	Yes	An object array with the context scenarios for inheritance	-
`locale`	Object	Yes	Object containing the attributes of the parent locale to be overloaded	-

Single Market Example: Context Widget en.intl.locale inherits from en.locale and changes the text of locale object submitButton if the market scope of the page request is "international"

{
  "parent": "en.locale",
  "context": {
    "markets": "intl"
  },
  "locale": {
    "sections": {
      "buttons": {
          "submitButton": "International Submit"
      }
    }
  }
}

Multi-Market Example: Context Widget en.multi.json inherits from en.json and changes the text of locale object submitButton if the market scope of the page request is "Germany" or "France"

{
  "parent": "en.locale",
  "context":  {
    "markets": ["Ger", "Fra"]
  },
  "locale": {
    "sections": {
      "buttons": {
        "submitButton": "German & France Submit"
      }
    }
  }
}

Using Locale Variables¶

At runtime, the locale JSON resources for the page's market context are merged, creating a Liquid object for the locale. This object can then be utilized within both Liquid templates and JSON attribute values, enabling dynamic and context-aware content across the page.

Example: Referencing the submitButton text within a component using the locale Liquid object allows for dynamic localization, ensuring the button text adapts to the page's market context.

    <button id="submitButton">{{ locale.sections.buttons.submitButton }}</button>

Example: Using the locale liquid object inside of hello-world-page.json

{
    "layout": "main.layout",
    "route": "/",
    "components": {
        "sample-component-01": {
            "id": "sample-component",
            "enabled": true,
            "blocks": {
                "heading_block": {
                    "type": "heading",
                    "settings": {
                        "heading": "{{ locale.sections.headers.welcomeMessage }}"
                    }
                }
            },
            "blockOrder": [
                "heading_block"
            ]
        }
    },
    "order": [
        "sample_component-01"
    ]
}