Localising the application

The Connect Earth API returns English copy by default. To present equivalents and tips to your users in another language, you can maintain your own library of translated strings on the customer side and look them up by the stable identifiers we return.

The same pattern applies to both equivalents and tips: our response always includes a stable key (or id), and your front end uses that key to fetch the translated string from a library you control. The numeric value we return — the CO2e estimate, the comparison amount — is substituted into a placeholder in your translated string at render time.

Localising equivalents

Carbon equivalents come back from the API with a key, a value, a unit, and an English text string. To display the equivalent in another language, ignore the text field and use the key to look up your own translated copy.

How it works

1. We return a stable key. Each equivalent has a key that does not change across responses — for example car, tree, or a more specific identifier such as TRANS_BEL_M_35 for a Belgian medium-sized transaction equivalent. The key identifies the comparison; the value is the number that goes with it.
2. You store a translated library on your side. Maintain a dictionary keyed by the equivalent key, mapping each key to a translated string with a placeholder for the value.
3. Your front end renders the localised string. When a response comes in, look up the key in your library and substitute the value into the placeholder.

Example

The API returns:

{
  "equivalents": [
    {
      "key": "car",
      "value": 1000,
      "unit": "km",
      "text": "This is equivalent to the emissions from driving an average car 1000 km."
    }
  ]
}

Your library (Bulgarian) might look like:

{
  "car": "Това е еквивалентно на емисиите от шофиране на средностатистическа кола {value} км."
}

Your front end substitutes the value into the placeholder and renders the localised string. Because the key is stable, the same library entry works regardless of the numeric value returned.

tip

Keep one library per language and switch based on the user's locale in your application. Update your library when we add new equivalents — the key list is the contract.

Localising tips

Tips follow the same pattern as equivalents, using the tip id as the stable key. The full mechanics of tips and recommendations — endpoint shapes, response structure, impact ratings, and filtering — are covered in Tips and recommendations. This section focuses only on localisation.

How it works

1. Each tip has a stable id. For example, ID_ELEC_3_1_3. The content field is the English copy; the id is the lookup key.
2. Maintain a local copy of the tip library on your side. As Tips and recommendations notes, we already recommend storing your own tip text locally so you can customise the wording. Translation is the same mechanism: your library maps each id to a string in your target language.
3. Render the localised string by id. When the API returns a tip, look up the id in your library and display your translated copy instead of the content field.

Example

The API returns:

{
  "tips": [
    {
      "id": "ID_ELEC_3_1_3",
      "content": "When replacing an appliance, you can reduce your energy bill and carbon emissions by purchasing one with a high energy-efficiency rating.",
      "impact_rating": "Medium"
    }
  ]
}

Your Bulgarian library entry:

{
  "ID_ELEC_3_1_3": "Когато сменяте уред, можете да намалите сметката си за енергия и въглеродните емисии, като купите уред с висок енергиен клас."
}

Recommendations work the same way — the reason object on the /recommendations endpoint contains structured parameters (GROUP_NAME, KG_CO2E, PERCENTAGE_CHANGE, etc.) that you substitute into a translated reason_text stored in your library, keyed by reason_id.

Where to start

1. Pull the current list of equivalent keys and tip IDs from your latest API responses, or ask Connect Earth for the full reference list.
2. Translate each string into your target language, preserving the placeholders.
3. Wire your front end to look up by key/id and substitute the numeric value at render time.
4. When we release new equivalents or tips, add the new keys to your library and translate them.