Introduction
In addition to editing text resource files, you can store your custom text resources in the database which has some unique advantages:
- Your custom text resources persist through version upgrades.
- You don't need to make changes in multiple servers when you use redundant setup.
Concepts
- 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
Container name |
---|
CommonServiceModelResources |
CrossDomainIdentityManagementResources |
GenericProviderResources |
LdapResources |
NemIdResources |
OAuth2Resources |
OtpResources |
RuntimeModelResources |
Saml2Resources |
StsResources |
UserNamePasswordResources |
WSFederationResources |
ModelResources |
Saml2ServiceResources |
WSFederationServiceResources |
WcfResources |
ClaimSelectorResources |
DataManagementServiceResources |
ExternalSamplesResources |
OAuth2ServiceResources |
RuntimeDiagnosticsResources |
SafeNetIntegration |
- 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:
Request URL:
1 2 |
GET https://#yourdomain/admin/api/rest/v2/localization/container Content-Type: application/json |
Response body:
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 |
{ "totalResults": 7, "resources": [ { "Container": "GlobalTextResources", "LanguageCode": "" }, { "Container": "GlobalTextResources", "LanguageCode": "da" }, { "Container": "GlobalTextResources", "LanguageCode": "en" }, { "Container": "GlobalTextResources", "LanguageCode": "nl" }, { "Container": "RuntimeModelResources", "LanguageCode": "da" }, { "Container": "RuntimeModelResources", "LanguageCode": "de" }, { "Container": "RuntimeModelResources", "LanguageCode": "nl" } ] } |
Get all keys and their value on the specific container
You can collect all keys and their value belonging to a specific container:
Request URL:
1 |
GET https://#yourdomain/admin/api/rest/v2/localization/container/{container} |
URI parameters:
Parameter | Description | Data Type | Parameter Type |
---|---|---|---|
container | The container to get | string | path |
languageCode | The language code | string | query |
Request body example:
1 |
https://#yourdomain/admin/api/rest/v2/localization/container/RuntimeModelResources?languageCode=da |
Response body:
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 |
{ "Container": "RuntimeModelResources", "LanguageCode": "da", "Items": [ { "Key": "AuthenticationList_UserNamePasswordPasswordLabel1", "Value": "Adgangskode - RuntimeModelResources - DA" }, { "Key": "RuntimeModelAuthenticationConnectionIdMismatch", "Value": "Uoverensstemmelse i autentificeringsforbindelses ID: Autentificeringsforbindelse ID fundet i endpoint konteksten ({0}) matcher hverken den der er fundet i kontekst ({1})." }, { "Key": "RuntimeModelAuthenticationConnectionMissingInSessionStateError", "Value": "Brugeren er autentificeret men har ingen ibrugtaget autentificeringsforbindelse. Hans session kan være udløbet eller et login link blev manuelt indsat i browseren." }, { "Key": "UserNamePasswordHelloUser", "Value": "Hej - DA" } ] } |
Add a text resource
You can add a text resource to a container without having to create the container in advance.
Request URL:
1 2 |
POST https://#yourdomain/admin/api/rest/v2/localization/text Content-Type: application/json |
Request body example:
1 2 3 4 5 6 |
{ "container": "GlobalTextResources", "languageCode": "en", "key": "HelloUser", "value": "Hello user" } |
Response body:
1 2 3 4 5 6 |
{ "container": "GlobalTextResources", "languageCode": "en", "key": "HelloUser", "value": "Hello user" } |
Add multiple text resources
Request URL:
1 2 |
POST https://#yourdomain/admin/api/rest/v2/localization/text/bulkinsert Content-Type: application/json |
Request body example:
1 2 3 4 5 6 7 8 9 10 11 12 13 14 |
[ { "container": "GlobalTextResources", "languageCode": "nl", "key": "HelloUser", "value": "Hej" }, { "container": "ClaimSelectorResources", "languageCode": "en", "key": "SelectClaim", "value": "Select a claim" } ] |
Response body:
1 2 3 4 5 6 7 8 9 10 11 12 13 14 |
[ { "Container": "GlobalTextResources", "LanguageCode": "nl", "Key": "HelloUser", "Value": "Hej" }, { "container": "ClaimSelectorResources", "languageCode": "en", "key": "SelectClaim", "value": "Select a claim" } ] |
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.
Request URL:
1 2 |
POST https://#yourdomain/admin/api/rest/v2/localization/container Content-Type: application/json |
Request body example:
1 2 3 4 5 6 7 8 9 10 |
{ "container": "GlobalTextResources", "languageCode": "da", "items": [ { "key": "HelloUser", "value": "Hej" } ] } |
Response body:
1 2 3 4 5 6 7 8 9 10 |
{ "container": "GlobalTextResources", "languageCode": "da", "items": [ { "key": "HelloUser", "value": "Hej" } ] } |
❗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 remove the ability to create containers with arbitrary in version 5.9.
Import text resources from a .resx file
Request URL:
1 2 |
POST https://#yourdomain/admin/api/rest/v2/localization/container/import Content-Type: multipart/form-data |
Request body example:
1 |
.resx file content |
Response body:
1 2 3 4 5 6 7 8 9 10 |
{ "container": "ClaimSelectorResources", "languageCode": "", "items": [ { "key": "ChooseAccountTitle", "value": "konto" } ] } |
Delete a text resource
Request URL:
1 |
DELETE https://#yourdomain/admin/api/rest/v2/localization/text/{container}/{key} |
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:
1 |
https://#yourdomain/admin/api/rest/v2/localization/text/ClaimSelectorResources/ChooseAccountTitle?languageCode=en |
Response body:
1 |
no content |
Delete a text resource container
Request URL:
1 |
DELETE https://#yourdomain/admin/api/rest/v2/localization/container/{container} |
URI parameters:
Parameter | Description | Data Type | Parameter Type |
---|---|---|---|
container | The container to delete | string | path |
languageCode | The language code | string | query |
Request body example:
1 |
https://#yourdomain/admin/api/rest/v2/localization/container/ClaimSelectorResources?languageCode=da |
Response body:
1 |
no content |
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.
- GlobalTextResources container
Syntax: @Resources.GlobalTextResources.Text["TextResourceKey"]
Example: @Resources.GlobalTextResources.Text["MyCustomText"]
- Built-in container
You can use the exact syntax that you have been using for long:
1 |
@Resources.UserNamePasswordResources.Title |
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}}