Traducoes (i18n)

Localized names for teams, leagues, countries, venues, and match status

Use o parametro ?lang= em qualquer endpoint da Football API para receber nomes traduzidos em PT-BR, ES, EN ou DE. As traducoes sao adicionadas como campos irmaos ao lado do campo original (ex.: name_long, name_short, name_sigla) — o campo original (name) nunca e sobrescrito, entao clientes existentes continuam funcionando sem mudancas.

Use the ?lang= parameter on any Football API endpoint to get localized names in PT-BR, ES, EN, or DE. Translations are added as sibling fields next to the original field (e.g., name_long, name_short, name_sigla) — the original field (name) is never overwritten, so existing clients keep working unchanged.

1. Como usar / How to use

Adicione ?lang=pt-br (ou es, en, de) a qualquer URL. Combine com o parametro key de autenticacao normalmente.

curl "https://football.api.insyde.one/fixtures?id=215662&lang=pt-br&key=YOUR_API_KEY"

Idiomas suportados / Supported languages:

2. Campos adicionados / Added fields

Para cada nome traduzivel encontrado na resposta, o edge consulta o dicionario e adiciona campos irmaos ao objeto. A forma da entrada no dicionario determina quais campos sao adicionados:

• _long — nome completo traduzido (ex.: "1. FC Colonia" para "1. FC Koln")
• _short — abreviacao curta para listas e cards (ex.: "Man Utd")
• _sigla — codigo de 3 letras estilo UEFA/FIFA (ex.: "MUN", "BAR")
• _desktop / _mobile — versoes responsivas para textos de status

3. Exemplo completo / Full example

Request:

GET https://football.api.insyde.one/fixtures?id=215662&lang=pt-br&key=YOUR_API_KEY

Response (recortado / trimmed):

{
  "response": [{
    "teams": {
      "home": {
        "id": 463,
        "name": "Aldosivi",                   // original, intocado
        "name_long": "Aldosivi",
        "name_short": "Aldosivi",
        "name_sigla": "ALD"
      },
      "away": {
        "id": 442,
        "name": "Defensa Y Justicia",
        "name_long": "Defensa y Justicia",
        "name_short": "Defensa",
        "name_sigla": "DYJ"
      }
    },
    "league": {
      "id": 128,
      "name": "Liga Profesional Argentina",
      "country": "Argentina",
      "country_long": "Argentina"             // country traduzido tambem
    },
    "fixture": {
      "status": {
        "long": "Match Finished",
        "short": "FT",
        "long_desktop": "Encerrado",          // versao desktop
        "long_mobile": "Enc."                 // versao mobile
      }
    }
  }]
}

4. Endpoints traduzidos / Translatable endpoints

O parametro lang aplica traducao apenas em endpoints que retornam nomes traduziveis. Em outros endpoints (/timezone, /seasons, etc.) o parametro e ignorado e a resposta passa direto.

5. Desambiguacao por escopo / Scoped disambiguation

A mesma string em ingles pode aparecer em contextos diferentes. Para esses casos o edge tenta uma chave composta antes de cair no lookup simples. Dois escopos suportados hoje:

The same English string can appear in different contexts. For those cases the edge tries a composite key before falling back to the plain key. Two scopes are supported today:

5.1 league.name por pais / by country

Serie A e usada pelo Brasileirao e pela Serie A italiana. O edge tenta "<name>__<country>" usando league.country do mesmo objeto.
Serie A is used by both the Brazilian top flight and the Italian one. The edge tries "<name>__<country>" using league.country from the same object.

{
  "Serie A__Brazil": { "long": "Brasileirao Serie A", "short": "Brasileirao", "sigla": "BRA" },
  "Serie A__Italy":  { "long": "Serie A",             "short": "Serie A",     "sigla": "SA"  }
}

5.2 venue.city por escopo / by scope

Sao Paulo aparece como cidade (venue.city) e tambem como nome de clube (team.name → Sao Paulo FC). Sem desambiguacao, a sigla do clube (SPFC/SAO) acaba sendo injetada como sigla da cidade. O edge tenta "<value>__city" antes da chave plana.
Sao Paulo appears as a city (venue.city) and as a club name (team.name → Sao Paulo FC). Without scoping, the club sigla (SPFC/SAO) ends up injected as the city's sigla. The edge tries "<value>__city" first, then falls back.

{
  "Sao Paulo":        { "long": "Sao Paulo", "short": "SPFC", "sigla": "SAO" },   // club
  "Sao Paulo__city":  { "long": "Sao Paulo" }                                      // city only
}

Entradas __city normalmente nao tem short nem sigla — cidades nao seguem o padrao TV. Sem entrada __city, o lookup cai na chave plana (comportamento atual).
__city entries typically don't carry short or sigla — cities don't follow the broadcast pattern. Without a __city entry, lookup falls back to the plain key (current behavior).

6. Headers de resposta / Response headers

7. Exemplos por linguagem / Examples by language

JavaScript (fetch):

const API_KEY = 'YOUR_API_KEY';
const BASE = 'https://football.api.insyde.one';

const res = await fetch(`${BASE}/fixtures?id=215662&lang=pt-br&key=${API_KEY}`);
const data = await res.json();

const match = data.response[0];
// Render: prefer short for mobile, long for desktop, fallback to original
const homeName = match.teams.home.name_short || match.teams.home.name_long || match.teams.home.name;
const statusLabel = match.fixture.status.long_mobile || match.fixture.status.long;

Python (requests):

import requests

API_KEY = "YOUR_API_KEY"
BASE = "https://football.api.insyde.one"

resp = requests.get(f"{BASE}/fixtures", params={
    "id": 215662,
    "lang": "pt-br",
    "key": API_KEY,
})
data = resp.json()

home = data["response"][0]["teams"]["home"]
# Use sigla (3-letter code) for compact display, fallback to short / name
display = home.get("name_sigla") or home.get("name_short") or home["name"]

8. Boas praticas / Best practices

• Use o campo original como fallback. Se uma entrada nao esta no dicionario o sibling pode estar ausente — sempre faca fallback para name.
  Use the original field as fallback. If an entry is not in the dictionary the sibling may be absent — always fall back to name.
• Escolha a variante por contexto. Tabelas/listas: name_short ou name_sigla. Headers, paginas detalhe: name_long. Status em cards mobile: long_mobile.
  Pick the variant per context. Tables/lists: name_short or name_sigla. Headers, detail pages: name_long. Status on mobile cards: long_mobile.
• Cache. Cada ?lang= tem cache CDN independente — TTL identico ao endpoint sem traducao. Nao ha custo adicional de latencia em hits.
  Cache. Each ?lang= has independent CDN cache — TTL identical to the untranslated endpoint. No extra latency cost on hits.
• Misses. Monitore x-i18n-missing para detectar entradas faltando no dicionario e reportar a curadoria.
  Misses. Monitor x-i18n-missing to detect dictionary gaps and report them to curation.

Back to Football API docs