# Get customiser language (`get_customiser_language`)

Reads one language a customiser publishes, addressed by its BCP 47 language code, and with include translations a filtered page of its translation entries as well. A language has no integer id: the language code is the identifier the public API uses. The translation page is bounded and filterable, because a customiser full dictionary is too large to return at once. It requires the customisers:read scope and has no side effects.

- Source URL: https://www.signcustomiser.com/help/mcp/tools/get_customiser_language/
- Markdown URL: https://www.signcustomiser.com/help/mcp/tools/get_customiser_language.md
- MCP endpoint: https://web.signcustomiser.com/mcp
- Required scope: `customisers:read`
- Behaviour: read

## Purpose

Read one language record, and read a bounded slice of its translation entries when the strings themselves are needed.

## Annotations

| Hint | Value |
| --- | --- |
| readOnlyHint | true |
| destructiveHint | false |
| idempotentHint | true |
| openWorldHint | false |

## Prerequisites

- A customiser id from list_customisers and a language code from list_customiser_languages.
- A merchant has connected this store and approved the customisers:read scope.

## Arguments

| Property | Type | Required | Description |
| --- | --- | --- | --- |
| `customiser_id` | integer | yes | The customiser id, from list_customisers. |
| `language_code` | string | yes | The BCP 47 language tag the language is addressed by, such as fr or pt-BR, from list_customiser_languages. |
| `include` | array of string | no | Add translations to return one filtered page of translation entries alongside the language record. |
| `translation_filter` | object | no | Filters applied to the translation page. Ignored unless include contains translations. An unknown filter is rejected, never ignored. |
| `translation_filter.group` | string | no | Only entries in this translation group. |
| `translation_filter.key` | string | no | Only entries whose key matches this value. |
| `translation_filter.required` | string | no | Only entries that are, or are not, required. One of: `true`, `false`. |
| `translation_filter.retired` | string | no | Only entries that are, or are not, retired. One of: `true`, `false`. |
| `limit` | integer | no | How many translation entries to return, between 1 and 100. Defaults to 20. Ignored unless include contains translations. |
| `cursor` | string | no | The opaque next_cursor value from the previous translation page, sent back with identical filters. |

## Result

One language record. With include translations, one page of translation entries and its own pagination block, never the whole dictionary.

| Property | Type | Required | Description |
| --- | --- | --- | --- |
| `request_id` | string | yes |  |
| `store` | object | yes |  |
| `store.id` | integer | yes |  |
| `store.name` | string | yes |  |
| `customiser_id` | integer | yes |  |
| `language` | object | yes | The language record. |
| `language.language_code` | string | yes |  |
| `language.source_language_code` | string or null | no |  |
| `language.display_name` | string or null | no |  |
| `language.status` | string | yes |  |
| `language.is_default` | boolean | yes |  |
| `language.translation_summary` | object or null | no |  |
| `language.ai_translation` | object or null | no |  |
| `language.published_at` | string or null | no |  |
| `language.updated_at` | string or null | no |  |
| `translations` | object | no | One page of translation entries, present only when include contained translations. |
| `translations.entries` | array of object | yes |  |
| `translations.pagination` | object | yes |  |
| `translations.pagination.has_more` | boolean | yes |  |
| `translations.pagination.next_cursor` | string or null | no |  |

## Error cases

| Code | Recovery |
| --- | --- |
| `insufficient_scope` | The connection was approved without customisers:read. |
| `invalid_parameter` | A translation filter is not one this API accepts; the accepted set is group, key, required and retired. |
| `resource_not_found` | No customiser with that id, or no language with that code on it. Call list_customiser_languages to rediscover a valid code. |

## Example: Read a language with its untranslated required keys

Request:

```json
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "get_customiser_language",
    "arguments": {
      "customiser_id": 42,
      "language_code": "fr",
      "include": [
        "translations"
      ],
      "translation_filter": {
        "required": "true"
      },
      "limit": 1
    }
  }
}
```

Response:

```json
{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "structuredContent": {
      "request_id": "req_01jz9x2k7c8f3m5n6p7q8r9s0t",
      "store": {
        "id": 12,
        "name": "Demo Signs"
      },
      "customiser_id": 42,
      "language": {
        "language_code": "fr",
        "source_language_code": "en",
        "display_name": "French",
        "status": "draft",
        "is_default": false,
        "translation_summary": {
          "key_count": 184,
          "required_key_count": 96,
          "translated_key_count": 12,
          "missing_required_key_count": 84,
          "publishable": false
        },
        "ai_translation": null,
        "published_at": null,
        "updated_at": "2026-05-04T09:11:20Z"
      },
      "translations": {
        "entries": [
          {
            "key": "selection:12:label",
            "group": "selections",
            "required": true,
            "source_text": "Colour",
            "draft_value": "Couleur",
            "published_value": null
          }
        ],
        "pagination": {
          "has_more": true,
          "next_cursor": "eyJrZXkiOiJzIn0"
        }
      }
    }
  }
}
```

## Example: A language code the customiser does not publish (error)

Request:

```json
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "get_customiser_language",
    "arguments": {
      "customiser_id": 42,
      "language_code": "zz"
    }
  }
}
```

Response:

```json
{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "isError": true,
    "structuredContent": {
      "error": {
        "code": "resource_not_found",
        "title": "Resource not found",
        "detail": "The requested resource does not exist or does not belong to the authenticated store.",
        "recovery": "The identifier does not exist in this store. Use the matching list tool to rediscover a valid id."
      }
    }
  }
}
```