Organizing i18n Keys with Namespaces and Scopes

Namespace Organization for i18n Keys

As applications grow, translation files can reach thousands of keys. Namespaces divide translations into logical groups, making files manageable and enabling code-splitting for performance.

What Is a Namespace?

A namespace is the top-level grouping of translation keys. In most i18n libraries, each namespace maps to a separate file:

locales/
  en/
    common.json       # Shared strings (buttons, labels, errors)
    home.json         # Home page specific strings
    settings.json     # Settings page specific strings
    auth.json         # Login, signup, password reset

Namespace Strategies

1. Per-Page Namespaces

Each page gets its own namespace:

pages.home.title
pages.home.hero.cta
pages.settings.profile.name
pages.settings.security.password

Best for: Content-heavy sites with many unique pages (marketing sites, CMS-driven apps).

2. Per-Component Namespaces

Each reusable component gets its own namespace:

components.header.logo_alt
components.header.menu_toggle
components.footer.copyright
components.sidebar.collapse

Best for: Component libraries and design systems with many shared UI elements.

3. Per-Feature Namespaces

Each feature module gets its own namespace:

features.checkout.cart.title
features.checkout.payment.card_number
features.user_profile.avatar.upload
features.notifications.preferences.email

Best for: Large applications with feature teams who own separate parts of the codebase.

4. Shared + Page Hybrid

A common namespace for shared strings plus per-page namespaces for unique content:

common.buttons.submit
common.buttons.cancel
common.errors.required_field
home.hero.title
home.features.item1.title

Best for: Most applications. The common namespace prevents duplication while page namespaces keep unique content organized.

Namespace Best Practices

• Keep the common namespace small (under 200 keys) -- only truly shared strings
• Never nest deeper than 4 levels (namespace.category.subcategory.key)
• Use consistent namespace names across all locales
• Load namespaces lazily in single-page applications for performance
• Document your namespace strategy in the project README or contributing guide