Building a Multi-Language App With the Country Languages API

Localization is one of the highest-leverage features you can ship: making your application speak the user's language directly increases conversion, retention, and trust. In this guide, we'll walk through using the Country Data API to look up the official languages of any country, then use that data to drive your application's language switching, content rendering, and locale formatting.

Why Country → Language Mapping Matters

Most localization libraries assume the user already picked a language. But the most common case is users arriving from search engines or paid ads with no previous session — and you want to serve them content in the right language from the very first page load.

The simplest reliable signal you have is the user's country, derived from IP geolocation, billing address, or a country selector. Once you know the country, you can look up its official languages and either pick one or offer them as choices.

How Many Languages Does a Country Have?

Many developers assume "one country = one language". That's wrong for a huge fraction of the world. Some examples:

Country	Official languages
Switzerland	German, French, Italian, Romansh
Belgium	Dutch, French, German
Canada	English, French
South Africa	11 languages (Zulu, Xhosa, Afrikaans, English, etc.)
India	Hindi, English (plus 22 scheduled languages)
Singapore	English, Malay, Mandarin Chinese, Tamil
Spain	Spanish, plus regional co-official: Catalan, Basque, Galician
Paraguay	Spanish, Guarani
Bolivia	Spanish, Quechua, Aymara (plus 34 indigenous languages)
Luxembourg	Luxembourgish, French, German

If your localization logic just maps US → English, FR → French, you'll deliver French content to users in Brussels (where Dutch-speaking Flemish users may dominate) and miss the chance to serve Quechua speakers in Bolivia.

Fetching Country Languages via API

The Country Data API includes a languages array in every country object:

GET https://api.countrydataapi.com/v1/countries/by-code?code=CH
Authorization: Bearer YOUR_API_KEY

Example response for Switzerland:

{
  "name": "Switzerland",
  "iso2": "CH",
  "iso3": "CHE",
  "languages": ["German", "French", "Italian", "Romansh"]
}

You can also filter countries by language to find every country that speaks a given language:

GET https://api.countrydataapi.com/v1/countries/by-language?language=Spanish
Authorization: Bearer YOUR_API_KEY

This returns a list of all countries where Spanish is an official or co-official language: Spain, Mexico, Colombia, Argentina, Peru, Venezuela, Chile, Ecuador, Cuba, the Dominican Republic, Honduras, Paraguay, El Salvador, Nicaragua, Guatemala, Costa Rica, Bolivia, Panama, Uruguay, and Equatorial Guinea.

End-to-End Example: Country-Driven Locale Detection

Here's a complete pattern for detecting the user's country and serving the right language. This example uses JavaScript on the client, but the same logic applies on the server.

// 1. Detect the user country (from IP, browser locale, or a selector)
function detectCountry() {
  // Try browser locale first
  const browserLang = navigator.language || 'en-US';
  const region = browserLang.split('-')[1];
  if (region) return region;

  // Fallback: use a free IP geolocation service or your own backend
  return 'US';
}

// 2. Fetch the country's languages from CountryDataAPI
async function getCountryLanguages(iso2) {
  const res = await fetch(`https://api.countrydataapi.com/v1/countries/by-code?code=${iso2}`, {
    headers: { 'Authorization': 'Bearer YOUR_API_KEY' }
  });
  const country = await res.json();
  return country.languages || [];
}

// 3. Pick the best language for your app
const SUPPORTED_LANGUAGES = ['en', 'es', 'pt', 'fr', 'de', 'it'];
const LANGUAGE_TO_CODE = {
  'English': 'en',
  'Spanish': 'es',
  'Portuguese': 'pt',
  'French': 'fr',
  'German': 'de',
  'Italian': 'it'
};

function pickBestLanguage(countryLanguages) {
  for (const lang of countryLanguages) {
    const code = LANGUAGE_TO_CODE[lang];
    if (code && SUPPORTED_LANGUAGES.includes(code)) {
      return code;
    }
  }
  return 'en'; // fallback
}

// 4. Wire it together
async function initLocale() {
  const country = detectCountry();
  const languages = await getCountryLanguages(country);
  const lang = pickBestLanguage(languages);
  document.documentElement.lang = lang;
  loadTranslations(lang);
}

initLocale();

This approach gives you sensible defaults without forcing the user to make a choice. You can still show a language switcher for users whose preferred language isn't the country's primary language.

Pitfalls and Edge Cases

Don't assume the order of the languages array implies primary vs secondary. Most APIs return languages in some declared order, but for genuinely multilingual countries (Switzerland, Belgium, Canada) you should treat them as equally official. Use additional signals (IP region within the country, browser preferences) to decide which one to pick.

Don't conflate language and locale. "Spanish" is a language. "es-MX" (Spanish as spoken in Mexico) is a locale that includes formatting rules — date format, number format, currency symbol position. The Country Data API gives you languages; for locale-specific formatting you need a tool like Intl or ICU.

Be careful with right-to-left languages. Arabic, Hebrew, Persian, and Urdu are read right-to-left. If you support these, set dir="rtl" on the HTML element and test your CSS layout.

Respect explicit user choices. If a user clicked the language switcher to pick English even though they're in Germany, store that preference and don't override it on their next visit.

Building a "Choose Your Language" Selector

For multilingual countries, the friendliest pattern is to detect the country, load its languages, and present them as a selector with the option pre-selected based on browser locale:

async function buildLanguageSelector(countryIso2) {
  const languages = await getCountryLanguages(countryIso2);
  if (languages.length <= 1) return; // no need to ask

  const select = document.createElement('select');
  for (const lang of languages) {
    const option = document.createElement('option');
    option.value = LANGUAGE_TO_CODE[lang] || 'en';
    option.textContent = lang;
    select.appendChild(option);
  }

  // Pre-select based on browser hint
  const browserLang = (navigator.language || 'en').split('-')[0];
  select.value = browserLang;

  select.addEventListener('change', (e) => {
    setLocale(e.target.value);
  });

  document.body.appendChild(select);
}

Get Started

To fetch country language data for your application, create a free account at CountryDataAPI. Plans start at $9.99/month with 10,000 monthly requests.

See related guides on ISO country codes, the countries by language endpoint, and the countries by region endpoint for region-aware experiences.