Introduction

Fetch the languages configured in your project to power multi-language content and locale detection.

More information about the module's user interface https://doc.oneentry.cloud/docs/category/languages

---

🎯 What does this module do?

The Locales module lets you fetch the active languages configured in your OneEntry project - so you can build internationalized applications that serve content in multiple languages.

Instead of hardcoding languages in your app, you fetch the list of active languages from OneEntry dynamically, allowing your content to adapt to the locales you have enabled (English, Russian, Arabic, Spanish, etc.). Languages are configured in the OneEntry admin panel; the SDK is read-only and only fetches them.

🚀 Quickstart

Initialize the module from defineOneEntry:

const { Locales } = defineOneEntry(
  "your-project-url", {
    "token": "your-app-token"
  }
);

Fetch the active locales and read their fields:

// Returns only active locales (isActive: true).
const locales = await Locales.getLocales();

console.log(`${locales.length} active languages`);

locales.forEach((locale) => {
  console.log(locale.code, locale.name, locale.shortCode);
});

✨ Key Concepts

What is a Locale?

A locale is a language and region combination that determines how content is displayed:

• Language Code - ISO 639-1 language code (e.g., en, ru, ar)
• Region Code - ISO 3166-1 country code (e.g., US, GB, RU)
• Locale Identifier - Combined format: language_REGION (e.g., en_US, ru_RU, ar_SA)

Examples:

Locale Code	Language	Region	Description
en_US	English	United States	American English
en_GB	English	Great Britain	British English
ru_RU	Russian	Russia	Russian
es_ES	Spanish	Spain	European Spanish
es_MX	Spanish	Mexico	Mexican Spanish
ar_SA	Arabic	Saudi Arabia	Arabic (Saudi Arabia)
fr_FR	French	France	French
de_DE	German	Germany	German

Locale Structure

Each locale returned by getLocales() (ILocalEntity) has:

{
  id: 146,                      // unique ID
  shortCode: 'en',              // short code
  code: 'en_US',                // full code
  name: 'English (USA)',        // name
  nativeName: 'English (USA)',  // native name
  isActive: true,               // is active (always true here)
  image: null,                  // image
  position: 1,                  // position
}

Locale Code vs. Short Code

Each locale has two code formats:

Field	Format	Example	Use For
code	language_REGION	en_US, ru_RU	Full locale identification
shortCode	language	en, ru	Language-only identification

---

📋 What You Need to Know

Locales are configured in the admin panel (read-only)

You cannot create, update, or delete locales via the SDK - they're configured in the OneEntry admin panel:

OneEntry Admin Panel → Settings → Languages → Add Language → Select Locale

The SDK is for fetching locale information only.

The SDK returns only active locales

getLocales() returns only the active language localization objects (isActive: true). Inactive locales configured in the admin panel are not returned, so there is no need to filter them out on the client. Each returned locale still carries the isActive flag (always true here), alongside code, shortCode, name, nativeName, image, and position.

There is no default-locale field in the response — choose and store a fallback language in your own app.

---

📊 Quick Reference Table

Method	Description	Use Case
getLocales()	Get all active locales	Fetch available languages

---

❓ Common Questions (FAQ)

How do I add new languages to my project?

You cannot add locales via the SDK. Locales are configured in the OneEntry admin panel.

---

Does getLocales() return inactive languages?

No. The SDK returns only active locales (isActive: true). Languages disabled in the admin panel are not included in the response.

---

Can I cache locales?

Yes. Locales rarely change, so caching the result is recommended for performance.

---

How do I handle missing translations?

Pick a fallback language in your app and fall back to it when content is missing for the requested locale — getLocales() does not include a default-locale field.

---

🎓 Best Practices

• Rely on the active list - The SDK already returns only enabled locales, so no client-side filtering is needed.
• Cache locales - They rarely change; cache the result for performance.
• Choose your own fallback language - There is no default-locale field; handle missing translations in your app.
• Match code vs shortCode - Use code (en_US) for full identification and shortCode (en) for language-only logic.

---

🔗 Related Documentation

• Pages Module - Fetch localized page content
• Products Module - Manage multi-language products
• GeneralTypes Module - Entity type classification
• Admins Module - Admin users who manage locales

---