Introduction

🎯 What does this module do?

The Locales module lets you manage multi-language support in your OneEntry project - retrieve available languages, detect user locale, and build internationalized applications that serve content in multiple languages.

Think of it as your language manager - instead of hardcoding languages in your app, you fetch the list of active languages from OneEntry dynamically, allowing your content to automatically adapt to different locales (English, Russian, Arabic, Spanish, etc.).

📖 Simple Explanation

In modern applications, you often need to support multiple languages:

🌍 E-commerce sites - Serve customers in different countries (English, French, German)
📱 Mobile apps - Adapt UI to user's device language
🌐 Websites - Show content in visitor's preferred language
📚 Documentation - Provide help in multiple languages
🎮 Games - Translate interface and content

The problem with hardcoding languages:

Issues:

🔄 Hard to update - Need to redeploy to add new languages
🌍 Not synchronized - App languages may differ from CMS languages
❌ Translation mismatches - Content exists in CMS but not in app
🔧 Manual maintenance - Update code every time languages change

The Locales solution:

Benefits:

🔄 Always in sync - Languages match what's configured in OneEntry
🌍 Dynamic - Add/remove languages without code changes
✅ Validated - Only show languages that have content
🎯 Centralized - Manage languages in one place

✨ 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 in OneEntry 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
  image: null,                  // image
  position: 1,                  // position
}

Why Use Locales Module?

Benefit	Description
Multi-language Support	Serve content in user's preferred language
Dynamic Language List	Languages sync with OneEntry configuration
Default Locale Detection	Automatically identify default language
Active Locale Filtering	Show only enabled languages
Centralized Management	Update languages in admin panel, not code
User Experience	Let users choose their language

Common Use Cases

Use Case	Description	Example
Language Selector	Dropdown menu to switch languages	Website header with language flags
Content Localization	Fetch content in user's language	Blog posts in English or Russian
Routing	URL structure per language	`/en/about`, `/ru/about`
Fallback Logic	Show default language if translation missing	Show English if Spanish not available
User Preferences	Remember user's language choice	Save locale in cookies/localStorage

📋 What You Need to Know

1. Locales are Configured in Admin Panel

You cannot create 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, not creating locales.

2. Active vs. Inactive Locales

Not all configured locales may be active:

Status	Meaning	When to Use
Active (`isActive: true`)	Locale is enabled and has content	Show in language selector
Inactive (`isActive: false`)	Locale is disabled or being prepared	Hide from users

Best practice: Always filter by isActive when building language selectors

3. Default Locale

Every OneEntry project has one default locale:

Default locale (isDefault: true) - The primary language
Used when no locale is specified
Fallback when translation is missing

4. 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

📊 Quick Reference Table

Method	Description	Returns	Use Case
`getLocales()`	Get all locales (active and inactive)	`Promise<Locale[]>`	Fetch available languages

Locale Structure:

interface Locale {
  id: number;
  shortCode: string;      // Language code only (e.g., "en")
  code: string;           // Full locale code (e.g., "en_US")
  name: string;           // Display name (e.g., "English (United States)")
  nativeName: 'English (USA)',
  isActive: boolean;      // Is locale enabled
  isDefault: boolean;     // Is default locale
  createdAt: string;
  updatedAt: string;
  image: null,
  position: number,
}

❓ Frequently Asked Questions (FAQ)

1. How do I add new languages to my project?

You cannot add locales via the SDK. Locales are configured in the OneEntry Admin Panel:

1. Log in to OneEntry Admin Panel
2. Go to Settings → Languages
3. Click "Add Language"
4. Select locale from dropdown (e.g., "French (France)")
5. Activate the locale
6. Save

Now fetch it via SDK:
const locales = await Locales.getLocales();
// Returns: [..., { code: "fr_FR", name: "French (France)", isActive: true }]

2. What's the difference between `code` and `shortCode`?

Field	Format	Example	Use For
`code`	Full locale (language + region)	`en_US`, `en_GB`	Specific regional content
`shortCode`	Language only	`en`	Language-level grouping

Best practice: Use code for fetching content, use shortCode for grouping/filtering.

3. How do I set the default language?

You cannot set default locale via SDK. The default locale is configured in OneEntry Admin Panel:

1. Go to Settings → Languages
2. Find the locale you want as default
3. Click "Set as Default"
4. Save

The SDK will reflect this change:
const locales = await Locales.getLocales();
const defaultLocale = locales.find(l => l.isDefault);
console.log(defaultLocale.code); // e.g., "en_US"

Note: Only one locale can be default at a time.

4. Should I show inactive locales to users?

No! Always filter by isActive:

Why? Inactive locales may:

Be in development (content not ready)
Be temporarily disabled
Not have translations for all content

5. How do I handle missing translations?

Use fallback logic

6. Can I cache locales?

Yes! Locales rarely change, so caching is recommended

8. Can I use Locales with Next.js i18n?

Yes! Integrate OneEntry locales with Next.js:

9. How do I group locales by language?

Group variants of the same language

10. What if I need to translate UI elements (not CMS content)?

OneEntry Locales module is for CMS content locales only. For UI translation:

Option 1: Use i18n library (react-i18next, next-i18next)

npm install react-i18next i18next

Option 2: Store UI translations in OneEntry

Create a "translations" page type and fetch translation strings

💡 Important Notes

⚠️ Locales are Read-Only

The Locales module is read-only:

✅ Fetch locales
✅ Filter by active status
✅ Find default locale
❌ Cannot create locales
❌ Cannot update locales
❌ Cannot delete locales

To modify: Use OneEntry Admin Panel.

🌍 Always Filter Active Locales

Only show active locales to users`

Why? Inactive locales may not have complete translations.

📦 Caching is Recommended

Locales rarely change - implement caching

🔄 Sync with Content Locales

Ensure UI languages match available content

🎓 Best Practices

✅ DO:

Always filter active locales - Show only enabled languages
Cache locales - They rarely change, cache for performance
Use default locale as fallback - Handle missing translations
Save user preference - Remember language choice
Validate locale codes - Check locale exists before using
Detect browser language - Auto-select user's language
Group by language - Show language variants logically
Use TypeScript for type safety - Leverage Locale interface

❌ DON'T:

Don't show inactive locales - Users can't access content
Don't hardcode locales - Always fetch dynamically
Don't ignore default locale - Essential for fallback
Don't fetch on every page load - Implement caching
Don't use IDs for locale selection - Use codes instead
Don't assume locales exist - Validate before using
Don't mix locale code formats - Be consistent (use code or shortCode)
Don't forget error handling - Always use try/catch

Definition of the Locales module

The 'Locales' module enables multi-language support in OneEntry.

Thanks to the support of multiple languages in OneEntry Platform, you can flexibly customize the interface of your dashboard and conveniently manage languages in your project. In this section, you can learn about the principles of working with languages.

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


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

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

Introduction

🎯 What does this module do?​

📖 Simple Explanation​

✨ Key Concepts​

What is a Locale?​

Locale Structure​

Why Use Locales Module?​

Common Use Cases​

📋 What You Need to Know​

1. Locales are Configured in Admin Panel​

2. Active vs. Inactive Locales​

3. Default Locale​

4. Locale Code vs. Short Code​

📊 Quick Reference Table​

❓ Frequently Asked Questions (FAQ)​

1. How do I add new languages to my project?​

2. What's the difference between code and shortCode?​

3. How do I set the default language?​

4. Should I show inactive locales to users?​

5. How do I handle missing translations?​

6. Can I cache locales?​

8. Can I use Locales with Next.js i18n?​

9. How do I group locales by language?​

10. What if I need to translate UI elements (not CMS content)?​

💡 Important Notes​

⚠️ Locales are Read-Only​

🌍 Always Filter Active Locales​

📦 Caching is Recommended​

🔄 Sync with Content Locales​

🎓 Best Practices​

✅ DO:​

❌ DON'T:​

Definition of the Locales module​

🔗 Related Documentation​