Core Concepts

This section explains the fundamental concepts that structure MovaBase. Understanding these concepts will help you effectively organize and manage your translations.

Organizations and Projects

MovaBase uses a hierarchical structure with organizations at the top level, containing projects within them.

Organization

An organization represents a workspace that groups related projects together under shared billing and team management.

Organization Properties

Each organization includes:

• Title: The organization name (e.g., "Acme Inc.", "Marketing Team")
• Description: Optional description to provide context
• Icon: An emoji to visually identify the organization
• Team Members: Users with assigned roles (Owner, Admin, Developer, Viewer)
• Subscription: Plan (Basic or Unlimited) with limits on projects, users, and translation keys
• Billing: Managed at the organization level

When to Use Multiple Organizations

Consider creating separate organizations when:

• You work with different clients or customers
• You have separate teams with different billing requirements
• You want to isolate different business units or departments
• You are a translation agency managing multiple client accounts

Projects

A project represents a distinct translation effort for a specific application, product, or component. Each project has its own set of languages, translations, files, and settings.

Project Properties

Each project includes:

• Name: Descriptive project name (e.g., "Mobile App", "Website", "Documentation")
• Description: Optional context about the project
• Icon: Emoji to visually identify the project
• Languages: Set of languages supported by this project
• Translations: All translation keys and values for this project
• Download Mode: How translations are structured when exported (file-based or language-based)
• Linked Project: Optional connection to another project to share translation keys
• Bitbucket Integration: Optional connection to sync with a repository
• Organization ID: Which organization owns this project

When to Use Multiple Projects

Create separate projects within an organization when:

• You have different applications or products that need translations
• You want to organize translations by feature or component
• Different teams work on different parts of your application
• You have different deployment environments (e.g., staging, production) with different translations

Organization vs. Project Hierarchy

Project Visibility and Access

Projects within an organization follow the organization's access control model:

NEEDS_MEDIA

Languages and Translations

Understanding how languages and translations are structured in MovaBase is essential for effective translation management.

Language Structure

Languages in MovaBase represent the target languages for your translations. Each language has the following properties:

Translation Keys and Values

Translations are organized as key-value pairs that map your application's translation keys to their localized values.

Translation Structure

Key Formats

Translation keys in MovaBase can use two formats:

Flat Keys: Simple, single-level keys

welcome_message
login_title
error_message

Nested Keys: Hierarchical keys using dot notation

auth.login.title
auth.login.button
auth.forgot_password.title

Translation Values

Translation values can be simple text strings or complex objects:

Simple Values: Plain text translations

"Welcome to our application!"
"Por favor, inicie sesión"

Complex Values: Objects with plural forms or variations

{
  "one": "1 item",
  "other": "5 items"
}

Default Language Concept

The default language serves as your source or base language. Key characteristics:

• Typically English or your primary development language
• Translation keys originate from this language
• Used as reference when creating new translations
• Often the first language added to a project
• Can be changed if needed

Translation Files

Translations are organized into files within each project. Files help group related translations together.

File Purpose

File Naming Conventions

Best practices for file naming:

• Use lowercase with underscores or hyphens
• Keep names descriptive but concise
• Avoid special characters (except underscores and hyphens)
• Use consistent naming across your project

Examples:

• common.json - Shared translations
• auth.json - Authentication-related translations
• checkout.json - Checkout flow translations
• user_dashboard.json - Dashboard page translations

NEEDS_MEDIA

Download Modes

MovaBase offers two download modes that determine how your translations are structured when exported. Understanding both modes helps you choose the right one for your project.

File-Based Mode

File-based mode organizes translations into separate files, creating a namespace-like structure. This is ideal for larger projects with many translations.

Structure

In file-based mode, translations are exported with the following structure:

/
├── en/
│   ├── common.json
│   ├── auth.json
│   ├── dashboard.json
│   └── settings.json
├── es/
│   ├── common.json
│   ├── auth.json
│   ├── dashboard.json
│   └── settings.json
└── fr/
    ├── common.json
    ├── auth.json
    ├── dashboard.json
    └── settings.json

When to Use File-Based Mode

Choose file-based mode when:

• Your application has distinct translation files for different features
• You want to maintain separation between different parts of your app
• Multiple developers work on different features simultaneously
• Your project has 50+ translation keys
• You're migrating from an existing project with file-based organization

Advantages

• Better organization for large projects
• Easier to merge conflicts in version control
• Clear separation of concerns
• Smaller individual files to load

Language-Based Mode

Language-based mode creates a single translation file for each language. This is simpler and works well for smaller projects.

Structure

In language-based mode, translations are exported with the following structure:

/
├── en.json
├── es.json
└── fr.json

Each JSON file contains all translations for that language.

When to Use Language-Based Mode

Choose language-based mode when:

• Your project is small with fewer translations
• You prefer a simple, flat structure
• You're starting a new project and want to keep things simple
• Your application loads all translations at once
• You have a single-page application

Advantages

• Simpler structure
• Easier to understand for new team members
• Single load point per language
• Less file management overhead

Download Mode Comparison

Switching Download Modes

You can change the download mode at any time from the project settings:

1. Open your project and click on the "Settings" tab
2. Navigate to the "General" section
3. Choose between "File-based" or "Language-based" mode
4. Click "Save Changes" to apply the new download mode to your project

NEEDS_MEDIA

Files and Organization

Understanding how files and folders work in MovaBase helps you structure your translations effectively.

File-Based Organization Structure

In file-based mode, translations are organized into files that act as containers for related keys.

File Structure Within MovaBase

MovaBase displays files in a hierarchical view:

Project Name
├── common.json
│   ├── welcome_message
│   ├── login_title
│   └── error_message
├── auth.json
│   ├── auth.login.title
│   ├── auth.login.button
│   └── auth.forgot_password.title
└── dashboard.json
    ├── dashboard.welcome
    ├── dashboard.stats.title
    └── dashboard.menu.items

Export Structure

When exported, files are organized by language code:

translations-file-based.zip
├── en/
│   ├── common.json
│   ├── auth.json
│   └── dashboard.json
├── es/
│   ├── common.json
│   ├── auth.json
│   └── dashboard.json
└── fr/
    ├── common.json
    ├── auth.json
    └── dashboard.json

Language-Based Organization Structure

In language-based mode, all translations are stored in a single file per language.

File Structure Within MovaBase

MovaBase displays all keys together, but knows which file they belong to:

Project Name
├── en (default)
│   ├── welcome_message
│   ├── login_title
│   ├── auth.login.title
│   ├── auth.login.button
│   └── dashboard.welcome
├── es
│   ├── welcome_message
│   ├── login_title
│   ├── auth.login.title
│   ├── auth.login.button
│   └── dashboard.welcome
└── fr
    ├── welcome_message
    ├── login_title
    ├── auth.login.title
    ├── auth.login.button
    └── dashboard.welcome

Export Structure

When exported, you get a single file per language:

translations-language-based.zip
├── en.json
├── es.json
└── fr.json

Each JSON file contains all translations for that language.

Key Naming Conventions

Effective key naming makes your translations easier to find and maintain.

Best Practices

Key Organization Examples

Authentication Keys

auth.login.title
auth.login.email_label
auth.login.password_label
auth.login.submit_button
auth.login.forgot_password_link
auth.signup.title
auth.signup.email_label
auth.signup.password_label

Navigation Keys

nav.home
nav.products
nav.about
nav.contact
nav.settings
nav.logout

Error Messages

error.network_failed
error.invalid_credentials
error.session_expired
error.server_error
error.unexpected_error

File Organization Best Practices

Organizing by Feature

Group translations by application feature:

auth.json
checkout.json
dashboard.json
profile.json
search.json

Organizing by Component

Group translations by UI component:

button.json
modal.json
form.json
header.json
footer.json

Organizing by Page

Group translations by application page:

home.json
about.json
contact.json
login.json
dashboard.json

File Size Considerations

NEEDS_MEDIA

Summary

Understanding these core concepts provides the foundation for effective translation management:

• Organizations group projects with shared billing and team management
• Projects contain translations for specific applications or products
• Languages represent target languages with their own properties
• Translations are key-value pairs that map to your application's text
• Download Modes determine export structure (file-based or language-based)
• Files organize translations into manageable groups

Part 2 of 14 • Core Concepts Complete

Next: Language Management