Skip to main content

Localization (loc-2.v1)

~/loc-2.v1 turns Agility's internal, English, machine-facing names into the words a user actually sees. Almost every other Agility API hands you raw identifiers — Scope, Timebox, AttributeDefinition'Name'Story — and leaves the display text to you. loc-2.v1 is where that display text comes from.

One request, many tags
curl "https://www.example.com/VersionOne/loc-2.v1?[Scope,Timebox,AttributeDefinition'Name'Story]" \
  -H "Accept-Language: en-US"
{
  "Scope": "Project",
  "Timebox": "Sprint",
  "AttributeDefinition'Name'Story": "Title"
}
note
The -2 matters

The endpoint is loc-2.v1, not loc.v1. loc-2.v1 is the bulk, JSON endpoint documented here. loc.v1 is the older single-tag, text/plain endpoint; it still exists and is described in Requests and responses.

Why This Section Is Unusually Deep​

The endpoint itself is trivial: send tags, get strings. What is not trivial is predicting the string you get back. The values are produced by a pattern-based localization engine whose behaviour is genuinely surprising if you have only seen the endpoint:

  • A tag is not a key. It is a stack of terms that resolves from most to least specific, so Plural'Story can be answered by a template registered under Plural. See Tag resolution.
  • Template bodies contain nested tags in {} that are resolved recursively, and can splice in the terms of the tag being resolved by numeric index. See Nested tag substitution.
  • A culture that has no entry falls back along a chain, and — the part nobody expects — nested tags inside a fallback template still resolve against the requested culture. See Culture fallback.
  • Several template sets are stacked on top of each other, later sets overriding earlier ones, and an empty value deletes an entry rather than blanking it. See Template sets and override order.
  • Templates are plain text files that are reloaded while the application is running. See Hot reload and caching.

If you are debugging a screen or an integration and want to see the raw tags instead of localized text, read Debugging with noloc first. It is the single most useful trick in this section and almost nobody knows about it.

When to Use It​

You want to…Use
Render an asset type name in a UIloc-2.v1?[Scope]
Render a field labelloc-2.v1?[AttributeDefinition'Name'Story]
Render many labels for one screenOne loc-2.v1?[…] request with every tag — it is designed for this
Discover which attributes exist in the first placemeta.v1, then localize the names you get back
Find out what an internal name meansGlossary

loc-2.v1 never tells you which tags exist. It is a pure resolver: any string you send is a valid tag, and an unmatched tag comes back unchanged. Discovery is meta.v1's job.

How Trustworthy Is This Section?​

Some older descriptions of this API are still in circulation and contradict this section in places. See Corrections to older documentation.

In This Section​

PageWhat it answers
Requests and responsesMethods, query syntax, response shapes, auth, errors, caching
Tag resolutionHow a tag's term stack is walked, and what wins
Nested tag substitution{} placeholders, numeric indices, literal braces, recursion
Culture fallbackAccept-Language, the fallback chain, partial matches
Template sets and override orderBase, edition sets, Company, terminology overrides, deletion
Template file formatThe .txt syntax, encoding, comments, continuations, escaping
Hot reload and cachingEditing templates on a running instance, and the ETag caveat
Debugging with nolocSeeing raw tags instead of localized output