[API Docs] Get SC Languages

Say you need to get a list of all the languages on Sutta Central, maybe so you can make a drop-down selector. This API will give you that. Either all languages including root languages (like Pali and Sanskrit) or just modern languages used for translations.

[ All API documentation | General discussion on APIs]

Requesting a list of languages

There is only a single endpoint:
https://suttacentral.net/api/languages

Returns:
An array of language objects
Example:

[
    {
        "uid": "af",
        "name": "Afrikaans",
        "iso_code": "af",
        "is_root": false,
        "localized": false,
        "localized_percent": 0
    },
    {
        "uid": "ar",
        "name": "Arabic",
        "iso_code": "ar",
        "is_root": false,
        "localized": false,
        "localized_percent": 0
    },
...
]

Object parts:

key value
uid (string) Two or three letter language code used in url parameters
name (string) Full language name
iso_code (string)
is_root (boolean) If it is a root text such as Pali or Sanskrit
localized (boolean) If there is support for this language in the website interface
localized_percent (numeric) How much of the interface has been localized

Parameters

There is a single parameter for this API: all=true

false: lists only target languages e.g. English, French, etc.
true: lists all languages including root

https://suttacentral.net/api/languages?all=true

Example Code

The following vanilla JS will create a language dropdown of all translation languages on SuttaCentral. English will be set as the default selection

const dropdown = document.getElementById("languages");

fetch(`https://suttacentral.net/api/languages`)
  .then(response => response.json())
  .then(data => {
    for (let i = 0; i < data.length - 1; i++) {
      dropdown.innerHTML += `<option value="${data[i].uid}" ${data[i].uid === "en" ? "selected" : ""}>${
        data[i].name
      }</option>`;
    }
  });

The following is a React component to generate a language dropdown, keeping the current selection in localStorage:

import { useEffect, useState } from "react";
export default function LanguagesDropdown() {
  let [languageList, setLanguageList] = useState([]);
  let [value, setValue] = useState(localStorage.language ? localStorage.language : "en");

  useEffect(() => {
    fetch(`https://suttacentral.net/api/languages`)
      .then(response => response.json())
      .then(data => {
        setLanguageList(data);
      });
  }, []);

  function handleChange(event) {
    setValue(event.target.value);
    localStorage.language = event.target.value;
  }

  return (
    <>
      <label htmlFor="languages" id="language-area-box-label">
        Language
      </label>
      Alternatives on SuttaCentral:
      <div className="option-descriptions dropdown-description">
        Choose a language to show alternatives to Bhikkhu Sujato's translation.
      </div>
      <select name="languages" id="languages" value={value} onChange={handleChange}>
        {languageList.map(language => {
          return (
            <option value={language.uid} key={language.uid}>
              {language.name}
            </option>
          );
        })}
      </select>
    </>
  );
}
Note: This is post is a wiki. Please feel free to click the edit button below to make changes. Feel free to reply to the post if you have questions
4 Likes

This is amazing, keep it up!

1 Like

It’s a lot of fun (yes, writing documentation passes for fun in my life). I hope it’s helpful for folks.

@HongDa or Bhante @Sujato, uid and iso_code appear to be identical. Is there one that should be prefered? Is one just legacy?

Also, is name hard coded? Or is it possible instead of getting “Deutsch” you could get “German”?