intl-namespace

To maintain a consistent, organized, and scalable approach to naming translation keys in your React components, we ask developers to follow a specific naming convention. This helps ensure that all translation keys are easily understandable and maintainable. Here’s how to structure your translation keys:

Guidelines

1. Use Unique Prefixes for Each Module

   • Ensure each module has a unique prefix. This helps avoid conflicts when translation keys are similar across different modules.
   • Example: Use user.profile.name and admin.profile.name instead of just profile.name.

2. Consistent Naming Convention

   • Stick to a consistent naming convention across all files. This includes using lower case, underscores or dots for separating words, and descriptive names.
   • Example: Use user.settings.update_email instead of UserSettings_UpdateEmail.

3. File-Based Namespacing

   • Divide translation files by modules and features. Each file should represent a specific module or feature.
   • Example:
     • user.json for user-related translations.
     • admin.json for admin-related translations.
     • dashboard.json for dashboard-related translations.

4. Avoid Generic Names

   • Avoid using generic names for keys that might be reused across different modules.
   • Example: Use dashboard.header.title instead of header.title.

5. Centralized Key Registry

   • Maintain a centralized registry of translation keys to track and manage the keys used across the project.
   • Use tools or scripts to check for duplicate keys and ensure consistency.

6. Environment-Based Namespacing

   • If translations are environment-specific, include the environment in the key.
   • Example: Use dev.user.profile.name and prod.user.profile.name.

7. Version Control and Review Process

   • Implement a version control system for translation files.
   • Establish a review process for adding new keys to ensure consistency and avoid conflicts.

8. Use Contextual Information

   • Add contextual information to translation keys to make their purpose clear.
   • Example: Use button.submit_form instead of just submit.

9. Document Translation Key Patterns

   • Document the patterns and conventions used for naming translation keys in the project's README or a dedicated document.

10. Fallback Strategy

    • Implement a fallback strategy for missing translations, specifying default values or default languages.

Example of Structured Translation Files

user.json

{
    "user": {
        "profile": {
            "name": "Name",
            "email": "Email",
            "update_button": "Update Profile"
        },
        "settings": {
            "update_email": "Update Email",
            "change_password": "Change Password"
        }
    }
}

admin.json

{
    "admin": {
        "dashboard": {
            "title": "Admin Dashboard",
            "user_management": "User Management"
        },
        "settings": {
            "site_configuration": "Site Configuration",
            "manage_roles": "Manage Roles"
        }
    }
}

dashboard.json

{
    "dashboard": {
        "header": {
            "title": "Dashboard",
            "welcome_message": "Welcome to your dashboard"
        },
        "statistics": {
            "total_users": "Total Users",
            "active_sessions": "Active Sessions"
        }
    }
}

Below note is internal to Admins

Merging Translation Files

When merging translation files, ensure that:

1. Consistent Naming: Ensure that all keys follow the consistent naming convention.
2. Unique Namespacing: Verify that the keys have unique namespaces to prevent conflicts.
3. Centralized Registry Check: Cross-check the centralized registry to ensure no duplicates.

Review Process

1. Automated Scripts: Use automated scripts to check for duplicate keys.
2. Peer Review: Implement a peer review process for adding or modifying translation keys.
3. Testing: Test the merged files in different environments to ensure no conflicts.

By following these additional standards and best practices, you can effectively manage and avoid conflicts when merging multiple translation files, ensuring a seamless and organized translation process.