> For the complete documentation index, see [llms.txt](https://developer.aiodds.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://developer.aiodds.com/bookmaker-odds/translate-overview.md).

# Translate Overview

We have added a "trans" field at both the market tier and the outcome tier.

Regardless of whether it comes from a Protobuf structure returned through MQTT over WebSocket, or from JSON data returned by an API endpoint, here is an example of an odd structure:

{% code expandable="true" %}

```json
{
  "market_id": 2625,
  "main_line": "",
  "outcomes": {
    "111358520": {
      "id": 111358520,
      "name": "3-0",
      "line": "",
      "status": 1,
      "value": "41",
      "uptime": 1764810022,
      "change": 0,
      "lost": 1,
      "trans": [
        "140",
        "3-0"
      ]
    },
    "242428685": {
      "id": 242428685,
      "name": "0-3",
      "line": "",
      "status": 1,
      "value": "15",
      "uptime": 1764808669,
      "change": 0,
      "lost": 1,
      "trans": [
        "140",
        "0-3"
      ]
    }
  },
  "trans": [
    "2553"
  ]
}
```

{% endcode %}

## Steps for applying translate

#### Step 1: A scheduled task that calls the translation API

`/v1/translate/market/list`\
`/v1/translate/outcome/list`

These two APIs provide incremental updates. The responses are sorted in ascending order by (updated\_at, id). 

For the initial request, pass (last\_updated\_at=0, last\_id=0). 

For subsequent requests, pass the (last\_updated\_at, last\_id) values from the last item of the previous response, i.e., (last\_updated\_at = data.list\[the\_last\_index].updated\_at, last\_id = data.list\[the\_last\_index].id). 

This way, you can retrieve the latest newly added or updated data.

{% hint style="info" %}
Since the translation data rarely changes, it's recommended to make incremental requests every few tens of seconds after the initial data fetch to keep the data updated.
{% endhint %}

#### Step 2: Market

`trans[[index=0]] = string(translation API response<"id">)`

Remember the index structure from the example above? We added a new translation-related key field: trans.

For the play types, we only look at the trans field at the same level as market\_id.

{% code expandable="true" %}

```
{
  "market_id": 2625,
  "main_line": "",
  "outcomes": {
    "111358520": {"id": 111358520, ...},
    "242428685": {"id": 242428685, ...}
  },
  "trans": [
    "2553"
  ]
}
```

{% endcode %}

In the structure above, for market\_id=2625, the trans field returns an array, whose first element is 2553.

Although market\_id may seem suitable as the primary key, the same market name can vary by sport\_id in some languages. A safer approach is to use (sport\_id, market\_id) as a composite key to map to the translation content. However, using a multi-field key is somewhat cumbersome, so we prefer to introduce a new ID specifically for handling translations. This ID is the primary key returned by the translate API.

Now check the translation API.

{% code expandable="true" %}

```
GET /v1/translate/market/list
[...
{
    "id": 2553,
    "sport_id": 0,
    "market_id": 2625,
    "market_name": "1st Half - Correct Score Without Any Other Score",
    "lang_es": "Marcador exacto Sin Ninguna Otra Anotación - 1.er Tiempo",
    "lang_en": "1st Half - Correct Score Without Any Other Score",
    "lang_tr": "1. Yarı - Doğru Skor Başka Skor Olmadan",
    "lang_de": "1. Halbzeit - Richtiges Ergebnis ohne jedes andere Ergebnis",
    "lang_ko": "전반전 - 다른 점수 없이 정확한 점수",
    "deleted": 0,
    "updated_at": 1764123965
},
{
    "id": 2554,
    "sport_id": 0,
    "market_id": 2626,
    "market_name": "2nd Half - Correct Score Without Any Other Score",
    "lang_es": "Marcador exacto Sin Ninguna Otra Anotación - 2.º Tiempo",
    ...
    "deleted": 0,
    "updated_at": 1764123965
},
...]
```

{% endcode %}

{% hint style="warning" %}
Note："id" is not "market\_id"
{% endhint %}

Let's ignore: sport\_id & market\_id;

{% code expandable="true" %}

```
"trans": [
    "2553"
]
```

{% endcode %}

The first string in trans (index=0) "2553" corresponds to the translation data with id=2553 in the primary key of the API response.

Translation API: id=2553, You can query the Korean translation: lang\_ko="전반전 - 다른 점수 없이 정확한 점수".

#### Step 3: Outcome

The structure in Outcome is similar to Market, but with one additional operation.

Take the following outcome structure as an example:

{% code expandable="true" %}

```
"111358520": {
  "id": 111358520,
  "name": "3-0",
  "line": "",
  "status": 1,
  "value": "41",
  "uptime": 1764810022,
  "change": 0,
  "lost": 1,
  "trans": [
    "140",
    "3-0"
  ]
},
```

{% endcode %}

You get trans:

{% code expandable="true" %}

```
"trans": [
    "140",
    "3-0"
]
```

{% endcode %}

Fetch the entry with id=140 from the translation API.

{% code expandable="true" %}

```
{
    "id": 140,
    "var": "$scores",
    "lang_es": "$scores",
    "lang_en": "$scores",
    "lang_tr": "$scores",
    "lang_de": "$scores",
    "lang_ko": "$scores",
    "deleted": 0,
}
```

{% endcode %}

var: It represents the variables in the outcome, for example, the score outcome(which cannot cover all possible score scenarios). If there are multiple variables, they are separated by commas: ','.

In trans, all elements except the first correspond one-to-one with the variables in var.

TransMap = var.split(",").zip(trans\[1..])

TransMap = {("$scores", "3-0"), }

In translation API's response id=140：lang\_ko="$scores", map TransMap, replace variables，get: lang\_ko="3-0"

{% code expandable="true" %}

```
eg.:
"trans": [
    "141", 
    "3"
]
&& 
{
    "id": 141,
    "var": "$score",
    "lang_es": "$score+",
    "lang_en": "$score+",
    "lang_tr": "$score+",
    "lang_de": "$score+",
    "lang_ko": "$score+",
    "deleted": 0,
}
-> lang_ko = "3+"
```

{% endcode %}

{% code expandable="true" %}

```
eg.:
"trans": [
    "153", 
    "[1,2,3]",
    "4,5"
]
&& 
{
    "id": 153,
    "var": "$scores_list,$scores",
    "lang_es": "$scores_list O $scores",
    "lang_en": "$scores_list Or $scores",
    "lang_tr": "$scores_list Veya $scores",
    "lang_de": "$scores_list Oder $scores",
    "lang_ko": "$scores_list Or $scores",
    "deleted": 0,
}
-> lang_ko = "[1,2,3] Or 4,5"
```

{% endcode %}


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://developer.aiodds.com/bookmaker-odds/translate-overview.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.