How to setup and use custom database text resources 

Introduction

In addition to editing text resource files, you can store your custom text resources in the database which has some unique advantages:

  1. Your custom text resources persist through version upgrades.
  2. You don't need to make changes in multiple servers when you use redundant setup.

Concepts

  1. Container

In database-based text resources context, a container is a bag of text resources and is the corresponding concept to a text resource file.
When you need to customize a built-in text resource of a text resource file or add a new language for it, for example, RuntimeModelResources.resx, you can create a RuntimeModelResources container and add your custom text resources there.
We can call them built-in containers because they are containers for built-in text resource files.
A container can be language-neutral or language-specific. To specify a language for a container, you can use 2-letter ISO language code, for example, RuntimeModelResources.da

  1. GlobalTextResources container

When you need to add a new text resource, you need to use the GlobalTextResources container. You can use the GlobalTextResources container for both Razor views and Liquid hosted forms.


Note that Container name, Language code, and Resource Key are all case-insensitive.


Setup

Currently, we are providing just enough REST API endpoints to provision text resources in the database. The most notable missing endpoint is the GET containers one.

In this section, we use the Swagger tool to show you how to work with all the new endpoints for custom text resources.

Get all containers

You can get all custom containers from an Identify instance:

get-container

Request URL:

Response body:

Get all keys and their value on the specific container

You can collect all keys and their value belonging to a specific container:

get-container-keys

Request URL:

URI parameters:

Parameter Description Data Type Parameter Type
container The container to get string path
languageCode The language code string query

Request body example:

Response body:

Add a text resource

You can add a text resource to a container without having to create the container in advance.

add-text-resource

Request URL:

Request body example:

Response body:

Add multiple text resources

add-muli-text-resource

Request URL:

Request body example:

Response body:


Note: The response currently doesn't follow the SCIM's specification. We will fix it in a future version.


Add a text resource container

The add text resource container endpoint can add multiple text resources to a single container. You can actually achieve the same goal by using the add multiple text resources endpoint.

add-text-container

Request URL:

Request body example:

Response body:


Warning: Although it is possible to create containers with any names that you like, we strongly recommend that you put all of your custom text resource keys into the GlobalTextResources container. We will remove the ability to create containers with arbitrary in near-future version.


Import text resources from a .resx file

import-file

Request URL:

Request body example:

Response body:

Delete a text resource

delete-text-resource

Request URL:

URI parameters:

Parameter Description Data Type Parameter Type
container The specific container of the text resource string path
languageCode The language code string query
key The specific text resource key to delete string path

Request body example:

Response body:

Delete a text resource container

delete-text-container

Request URL:

URI parameters:

Parameter Description Data Type Parameter Type
container The container to delete string path
languageCode The language code string query

Request body example:

Response body:

How to use your newly added text resources

Let's assume that we had created a GlobalTextResources container with a new text resource named “NewTextResource” by using the REST API endpoints above.
You can use it for both Razor views and Hosted forms.

Razor views

The syntaxes that you can use depends on whether your custom text resource is in the GlobalTextResources container or a built-in container.

  1. GlobalTextResources container

Syntax: @Resources.GlobalTextResources.Text["TextResourceKey"]

Example: @Resources.GlobalTextResources.Text["MyCustomText"]

  1. Built-in container

You can use the exact syntax that you have been using for long:

Please note that built-in container usage implies that the text resource exists in one of the built-in text resource files. Therefore, @Resources.UserNamePasswordResources.MySuperAwesomeNewTextResource won't work.

You can also retrieve the text resource via the GlobalTextResources container:

Syntax: @Resources.GlobalTextResources.Text["ContainerName.TextResourceKey"]

Example: @Resources.GlobalTextResources.Text["UserNamePasswordResources.Title"]

Hosted forms

For hosted forms, you can use the same synxtax for text resources in both GlobalTextResources container and built-in containers.

syntax: {{Resources.ContainerName.TextResourceKey}}

For example:

{{Resources.RuntimeModelResources.TextResourceKey}}

{{Resources.GlobalTextResources.NewTextResource}}