Skip to main content

Localization Endpoints

Digital.ai Agility provides localization endpoints that translate system strings, asset type names, and attribute definitions into locale-specific text. These endpoints help build multilingual integrations and custom user interfaces.

Overview​

The localization endpoints allow clients to retrieve locale-specific translations for:

  • Asset type names (e.g., "Story" → "User Story", "Scope" → "Project")
  • Attribute definition labels (e.g., "Name" → "Title")
  • System messages and error text

Both endpoints support fallback behavior: if a translation doesn't exist for the requested locale (e.g., French-Canadian fr-ca), the system searches the base language (fr), then English (en). If no translation exists, the original string is returned unchanged.

loc.v1 - Single String Localization​

The loc.v1 endpoint translates a single input string. For bulk translations, use loc-2.v1 instead.

FieldValue
URL Form<Server Base URI>/loc.v1?<localizable_string>
AuthenticationNone
HTTP Request VerbGET
Response Content Typetext/plain

Request Parameters​

localizable_string​

The query parameter takes a single string to localize. This parameter does not use the standard name=value format. Instead, Digital.ai Agility attempts to localize the entire query string content after the question mark.

Setting the Locale​

To retrieve a localized string for a specific locale, set the Accept-Language HTTP header in the request.

Example: Use French-Canadian translations

Accept-Language: fr-ca

Examples​

Translate an Asset Type Name​

Retrieve the localized name of the Scope asset type for display:

<Server Base URI>/loc.v1?Scope

Response:

Project
note

Scope is the internal VersionOne name for a project, sub-project, or release.

Translate an Attribute Definition​

Retrieve the display name for the Story.Name attribute:

<Server Base URI>/loc.v1?AttributeDefinition'Name'Story

Response:

Title

The response "Title" corresponds to the field label used in the Agility application.

loc-2.v1 - Multiple Strings Localization​

The loc-2.v1 endpoint translates multiple strings in a single request, returning a JSON object with key-value pairs for each translation. This endpoint supports both single and bulk translations. It is recommended over loc.v1 for all use cases.

FieldValue
URL Form<Server Base URI>/loc-2.v1?<json_string_array>
AuthenticationNone
HTTP Request VerbGET
Response Content Typeapplication/json

Request Parameters​

json_string_array​

The query parameter takes a JSON array of strings to localize. This parameter does not use the standard name=value format. Digital.ai Agility attempts to localize each string in the comma-separated array.

Format:

[String1,String2,String3]

Setting the Locale​

To retrieve localized strings for a specific locale, set the Accept-Language HTTP header in the request.

Example: Use French-Canadian translations

Accept-Language: fr-ca

Examples​

Translate Multiple Asset Type Names​

Retrieve the localized names of the Scope and Timebox asset types:

<Server Base URI>/loc-2.v1?[Scope,Timebox]

Response:

{
  "Scope": "Project",
  "Timebox": "Sprint"
}
note
  • Scope is the internal VersionOne name for a project, sub-project, or release
  • Timebox is the internal VersionOne name for an iteration or sprint

Translate Multiple Attribute Definitions​

Retrieve the display names for Story.Name and Story.Description:

<Server Base URI>/loc-2.v1?[AttributeDefinition'Name'Story,AttributeDefinition'Description'Story]

Response:

{
  "AttributeDefinition'Name'Story": "Title",
  "AttributeDefinition'Description'Story": "Description"
}

The response contains field labels corresponding to those used in the Agility application.

Fallback Behavior​

Both endpoints implement a locale fallback chain:

  1. Requested locale (e.g., fr-ca for French-Canadian)
  2. Base language (e.g., fr for French)
  3. English (en)
  4. Original string (if no translation found)

This ensures consistent behavior across all locales while providing the most appropriate translation available.

Common Use Cases​

Building Multilingual UIs​

Use loc-2.v1 to retrieve all necessary translations in a single request:

// Get translations for Story fields
GET /loc-2.v1?[Story,AttributeDefinition'Name'Story,AttributeDefinition'Description'Story,AttributeDefinition'Estimate'Story]

Localizing Error Messages​

When the API returns unlocalized error messages or system strings, pass them to loc.v1 or loc-2.v1 for translation:

// Translate system message
GET /loc.v1?Required.Story.Name

Displaying Asset Type Lists​

Retrieve localized names for all asset types in a dropdown or navigation menu:

// Get all primary workitem types
GET /loc-2.v1?[Story,Defect,TestSet,Task]