# How OpenSEO Manages Multi-Language Locations: Switzerland de/fr/it Implementation Guide

> Learn how OpenSEO manages multi-language locations like Switzerland de fr it. Discover its data storage and validation for seamless international SEO.

- Repository: [Every App/open-seo](https://github.com/every-app/open-seo)
- Tags: implementation-guide
- Published: 2026-09-04

---

**OpenSEO handles multi-language locations by storing a catalog of DataForSEO location codes paired with default languages and explicit multi-language mappings, enabling validated language selection for countries like Switzerland that support German, French, and Italian.**

OpenSEO implements a robust localization architecture to manage SEO data retrieval across regions with multiple official languages. The system maintains type-safe registries in TypeScript that define which languages are valid for each numeric location code, ensuring that API requests to DataForSEO only contain supported locale combinations and preventing costly validation errors.

## Location and Language Architecture in OpenSEO

The foundation of OpenSEO’s multi-language support rests on three coordinated data structures defined in **[`src/shared/keyword-locations.ts`](https://github.com/every-app/open-seo/blob/main/src/shared/keyword-locations.ts)**. 

First, each country maps to a numeric `code` (e.g., `2756` for Switzerland). Second, the `LOCATION_LANGUAGE` constant associates every location code with its primary default language. Third, the `MULTI_LANGUAGE_LOCATIONS` registry explicitly enumerates countries that support additional languages beyond their default.

For Switzerland, this registry defines the available language codes as an array:

```typescript
2756: ["de", "fr", "it"], // Switzerland

```

This approach allows the system to distinguish between single-language countries (which rely solely on the default language mapping) and multi-language regions that require explicit user selection capabilities.

## Resolving Language Options for UI Components

When rendering language pickers in the frontend, OpenSEO calls **`getLanguageOptions(locationCode)`** to build a filtered list of valid choices. This function checks the `MULTI_LANGUAGE_LOCATIONS` map first; if the location exists in the registry, it uses those codes, otherwise falling back to the single default language.

Located around line 814 in [`src/shared/keyword-locations.ts`](https://github.com/every-app/open-seo/blob/main/src/shared/keyword-locations.ts), the implementation uses a `Set` to deduplicate codes before filtering the global `SERP_LANGUAGE_OPTIONS`:

```typescript
export function getLanguageOptions(locationCode: number) {
  const codes = new Set(
    MULTI_LANGUAGE_LOCATIONS[locationCode] ?? [getLanguageCode(locationCode)],
  );
  return SERP_LANGUAGE_OPTIONS.filter((language) => codes.has(language.code));
}

```

For Switzerland (code `2756`), this returns German, French, and Italian options, while a country like the United States would return only English.

## Market Resolution and Validation

Before issuing requests to the DataForSEO SERP API, OpenSEO must resolve which language code to transmit. The **`resolveMarket`** function handles this logic by accepting user arguments and project defaults, automatically selecting the location’s default language when none is specified:

```typescript
export function resolveMarket(args, project) {
  const locationCode = args.locationCode ?? project.locationCode;
  const languageCode =
    args.languageCode ??
    (locationCode === project.locationCode
      ? project.languageCode
      : getLanguageCode(locationCode));
  return { locationCode, languageCode };
}

```

For validation, **`assertLanguageForLocation`** in [`src/server/lib/market.ts`](https://github.com/every-app/open-seo/blob/main/src/server/lib/market.ts) (around line 34) guards against invalid combinations. It utilizes **`isLanguageServedForLocation`**, which references the same `MULTI_LANGUAGE_LOCATIONS` data to verify that a requested language is actually served for the target location before any external API call occurs.

## Keyword Data API Language Handling

The DataForSEO Labs endpoints (keyword data) impose stricter language constraints than the SERP API, accepting only a country’s supported languages. To handle this, **`resolveKeywordDataLanguage`** validates the requested language against `getLanguageOptions` and falls back to the location’s default when an unsupported language is supplied:

```typescript
return getLanguageOptions(locationCode).some(o => o.code === languageCode)
  ? languageCode
  : getLanguageCode(locationCode);

```

This ensures that requests to Labs-based tools never trigger "Invalid Field: ‘language_code’" errors, automatically correcting selections like Spanish (`es`) for Switzerland to German (`de`).

## Practical Implementation Examples

The following patterns demonstrate how OpenSEO’s multi-language utilities function in practice:

```typescript
import { getLanguageOptions, resolveMarket, resolveKeywordDataLanguage } from '@/shared/keyword-locations';

// 1. Retrieve supported languages for Switzerland
const swissLangs = getLanguageOptions(2756);
console.log(swissLangs.map(l => l.label)); // → ["German", "French", "Italian"]

// 2. Resolve market when user selects location without specifying language
const market = resolveMarket(
  { locationCode: 2756 }, 
  { locationCode: 2144, languageCode: 'en' }
);
// market = { locationCode: 2756, languageCode: 'de' } – defaults to German

// 3. Validate language for Labs keyword-data API with fallback
const validLang = resolveKeywordDataLanguage(2756, 'fr');
console.log(validLang); // → "fr"

const fallbackLang = resolveKeywordDataLanguage(2756, 'es');
console.log(fallbackLang); // → "de" (fallback to default)

```

## Summary

- **Registry-based architecture**: OpenSEO stores location definitions in [`src/shared/keyword-locations.ts`](https://github.com/every-app/open-seo/blob/main/src/shared/keyword-locations.ts), separating default languages from explicit multi-language mappings.
- **Switzerland support**: Location code `2756` explicitly lists `["de", "fr", "it"]` in the `MULTI_LANGUAGE_LOCATIONS` constant.
- **Dynamic UI generation**: The `getLanguageOptions` function filters available languages based on the registry, presenting only valid choices to users.
- **Early validation**: `assertLanguageForLocation` in [`src/server/lib/market.ts`](https://github.com/every-app/open-seo/blob/main/src/server/lib/market.ts) prevents invalid API requests before they reach DataForSEO.
- **Intelligent fallback**: `resolveMarket` and `resolveKeywordDataLanguage` automatically default to the location’s primary language when unspecified or invalid.

## Frequently Asked Questions

### Which countries does OpenSEO support for multi-language SEO targeting?

OpenSEO supports any country defined in the DataForSEO location catalog, with explicit multi-language definitions for regions like Switzerland (`2756`), Belgium, and Canada. The `MULTI_LANGUAGE_LOCATIONS` constant in [`src/shared/keyword-locations.ts`](https://github.com/every-app/open-seo/blob/main/src/shared/keyword-locations.ts) enumerates countries where multiple language options are exposed in the UI, while all other locations default to their single primary language defined in `LOCATION_LANGUAGE`.

### How does OpenSEO prevent invalid language codes in DataForSEO API calls?

Before transmitting requests, OpenSEO calls `assertLanguageForLocation` which utilizes `isLanguageServedForLocation` to check the requested language against the `MULTI_LANGUAGE_LOCATIONS` registry. If the combination is invalid, the system throws an error or falls back to the default language (in the case of Labs endpoints via `resolveKeywordDataLanguage`), preventing "Invalid Field" errors from the DataForSEO API.

### What happens when a user selects a language not supported for a specific location?

For SERP API calls, OpenSEO validates the language early and rejects unsupported combinations. For Labs keyword-data endpoints, the system automatically falls back to the location’s default language. For example, requesting Spanish (`es`) for Switzerland (`2756`) results in the system defaulting to German (`de`) to ensure the API call succeeds.

### How does the system handle language selection when a user changes locations mid-project?

The `resolveMarket` function in [`src/shared/keyword-locations.ts`](https://github.com/every-app/open-seo/blob/main/src/shared/keyword-locations.ts) compares the requested `locationCode` against the project's current location. When they differ, it automatically resolves the language to the new location’s default via `getLanguageCode`, ensuring that switching from a project based in the UK to one targeting Switzerland automatically adopts German unless explicitly overridden.