Skip to main content

Namespaces

Namespaces are a powerful organizational feature that allows you to group and structure your translation keys within a project. They provide a way to logically separate keys, making it easier to manage large projects and organize translations by feature, module, or any other organizational structure.

Concepts of Namespaces​

  • Name
    A unique identifier for the namespace within your project. Names can only contain alphanumeric characters, underscores, and hyphens, with a maximum length of 50 characters.

  • Description
    A brief description of what the namespace represents, helping team members understand its purpose and scope.

  • Organization
    Namespaces help organize keys into logical groups, making it easier to filter, manage, and export specific subsets of your translations.

  • Project-level Feature
    Namespaces must be enabled for your project in the Settings before they can be used. Once enabled, you can create multiple namespaces and assign keys to them.

Enabling Namespaces​

Before you can use namespaces, you need to enable them for your project:

  1. Go to your project Settings
  2. Enable the Enable Namespaces option
  3. Save your settings

Once enabled, you can start creating and managing namespaces.

Creating a Namespace​

To create a new namespace:

  1. Navigate to your project
  2. Go to the Namespaces section
  3. Click Create Namespace
  4. Enter a unique name (alphanumeric characters, underscores, and hyphens only, max 50 characters)
  5. Add a description to help your team understand the namespace's purpose
  6. Save the namespace
tip

Use descriptive namespace names that reflect their purpose, such as authentication, dashboard, error-messages, or user-profile. This makes it easier for your team to understand the organization structure.

Assigning Keys to Namespaces​

When creating or editing a key, you can assign it to a namespace. This helps organize your translations and makes it easier to:

  • Filter keys by namespace
  • Export specific namespaces
  • Manage translations for specific features or modules
  • Use namespace-based CDN downloads

Managing Namespaces​

Viewing All Namespaces​

You can view all namespaces in your project, along with their descriptions and creation information.

Editing a Namespace​

You can update the name and description of a namespace at any time. However, keep in mind that changing a namespace name may affect how keys are organized and how they appear in exports.

Deleting a Namespace​

A namespace can only be deleted if it's not currently assigned to any keys. If you need to delete a namespace that's in use:

  1. First, reassign or remove the namespace from all keys that use it
  2. Then delete the namespace
warning

Important: You cannot delete a namespace that is currently assigned to keys. Make sure to reassign or remove the namespace from all keys before attempting to delete it.

Using Namespaces with CDN​

When namespaces are enabled, you can use namespace-based CDN downloads to fetch translations organized by namespace. This is particularly useful for:

  • Loading translations for specific features on demand
  • Reducing the size of translation bundles
  • Organizing translations by application modules

See more about Content Delivery for details on using namespaces with CDN.

Best Practices​

  • Use Clear Naming: Choose namespace names that clearly indicate their purpose
  • Consistent Organization: Establish a consistent naming convention across your project
  • Logical Grouping: Group related keys together in the same namespace
  • Documentation: Use descriptions to explain the purpose and scope of each namespace
  • Plan Before Enabling: Consider your organizational structure before enabling namespaces, as reorganizing can be time-consuming