---
id: loc-2-v1
slug: /apis/loc-2-v1
title: 'Localization (loc-2.v1)'
description: 'The localization API and the localizer engine behind it: term stacks, nested substitution, culture fallback, template set overrides, hot reload and noloc.'
sidebar_label: 'Overview'
sidebar_position: 1
tags: ['api', 'localization', 'terminology', 'i18n']
sourceRefs:
  ['versionone-localization', 'core-docsource-loc', 'api-docs-loc', 'core-source']
draft: false
---

`~/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.

```bash title="One request, many tags"
curl "https://www.example.com/VersionOne/loc-2.v1?[Scope,Timebox,AttributeDefinition'Name'Story]" \
  -H "Accept-Language: en-US"
```

```json
{
  "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](/apis/loc-2-v1/requests-and-responses#legacy-locv1).
:::

## 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](/apis/loc-2-v1/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](/apis/loc-2-v1/nested-tags).
- 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](/apis/loc-2-v1/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](/apis/loc-2-v1/template-sets).
- Templates are plain text files that are **reloaded while the application is
  running**. See [Hot reload and caching](/apis/loc-2-v1/hot-reload).

If you are debugging a screen or an integration and want to see the raw tags
instead of localized text, read [Debugging with `noloc`](/apis/loc-2-v1/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 UI                             | `loc-2.v1?[Scope]`                                                          |
| Render a field label                                          | `loc-2.v1?[AttributeDefinition'Name'Story]`                                 |
| Render many labels for one screen                             | One `loc-2.v1?[…]` request with every tag — it is designed for this          |
| Discover which attributes exist in the first place            | [meta.v1](/apis/meta-v1), then localize the names you get back              |
| Find out what an internal name _means_                        | [Glossary](/reference/glossary)                                             |

`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](/apis/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](/apis/loc-2-v1/requests-and-responses#corrections-to-older-documentation).

## In This Section

| Page                                                                        | What it answers                                                     |
| --------------------------------------------------------------------------- | ------------------------------------------------------------------- |
| [Requests and responses](/apis/loc-2-v1/requests-and-responses)             | Methods, query syntax, response shapes, auth, errors, caching       |
| [Tag resolution](/apis/loc-2-v1/tag-resolution)                             | How a tag's term stack is walked, and what wins                     |
| [Nested tag substitution](/apis/loc-2-v1/nested-tags)                       | `{}` placeholders, numeric indices, literal braces, recursion       |
| [Culture fallback](/apis/loc-2-v1/culture-fallback)                         | `Accept-Language`, the fallback chain, partial matches              |
| [Template sets and override order](/apis/loc-2-v1/template-sets)            | `Base`, edition sets, `Company`, terminology overrides, deletion    |
| [Template file format](/apis/loc-2-v1/template-file-format)                 | The `.txt` syntax, encoding, comments, continuations, escaping      |
| [Hot reload and caching](/apis/loc-2-v1/hot-reload)                         | Editing templates on a running instance, and the ETag caveat        |
| [Debugging with `noloc`](/apis/loc-2-v1/noloc)                              | Seeing raw tags instead of localized output                         |

## Related Topics

- [meta.v1](/apis/meta-v1) — discover the asset types and attribute definitions whose names you localize
- [API conventions](/apis/conventions) — base URL and header conventions shared across endpoints
- [Glossary](/reference/glossary) — what Agility's internal names mean
- [HTTP status codes](/reference/status-codes)