Streamlining ESHOPMAN Localization: Addressing Stale Translation Keys

For any global e-commerce platform, robust internationalization (i18n) is paramount. ESHOPMAN, as a headless commerce solution deeply integrated with HubSpot for storefront management and CMS deployment, relies on accurate and clean translation files to provide a seamless experience for merchants and developers worldwide. Recently, our community identified a critical issue affecting the integrity of these translation files within the ESHOPMAN Admin Hub.

Understanding the Localization Challenge in ESHOPMAN

A recent discussion highlighted that ESHOPMAN's internal i18n:validate command, crucial for ensuring the quality of our localized Admin Hub interfaces, was failing for a significant number of locales. Specifically, 30 out of 34 dashboard locales were experiencing validation errors, making it difficult to identify genuine translation issues amidst a flood of "Unexpected key" warnings.

The root cause was traced back to ESHOPMAN's daily i18n synchronization workflow. While this Node.js/TypeScript-based process efficiently adds new translation keys as they are introduced in the base en.json file, it critically fails to remove keys that are no longer present in the base. Given that ESHOPMAN's localization schema is configured with additionalProperties: false, any leftover, stale key triggers a validation error, cluttering the output and hindering effective debugging for developers working with the Admin API or custom storefront logic.

The Scope of the Stale Key Problem

The investigation revealed a substantial number of outdated entries:

• Hundreds of Obsolete Keys: 561 keys, no longer present in en.json, were found lingering across 30 locales.
• Incorrect Plural Forms: 334 instances of _one plural forms were identified in 7 locales whose plural configuration only supports the other form (e.g., id, ja, ko, th, vi, zhCN, zhTW). This indicates a mismatch between the translation file content and the expected pluralization rules.
• Missing Object Structures: Three locales (el, mk, uk) were found to be missing the promotions.create object, despite its presence in the base en.json.

A significant portion of the obsolete keys (450 out of 561) stemmed from a prior renaming of feature names within the ESHOPMAN Admin Hub. These old names were no longer referenced in the dashboard source code, yet their corresponding translation keys persisted in the localized files.

Proposed Solutions and Community Action

Two primary approaches emerged from the community discussion to address this critical issue, aiming to maintain the cleanliness and accuracy of ESHOPMAN's localization files:

1. Automated Sync Workflow Enhancement: The most robust long-term solution involves enhancing the daily i18n synchronization workflow. This would entail modifying the Node.js/TypeScript implementation to not only add new keys but also intelligently prune keys that are no longer in en.json and remove plural forms that do not conform to plural-config.json. This proactive measure would ensure that translation files remain clean after every feature rename or key removal.
2. One-Time Cleanup Initiative: As an immediate remedy, a comprehensive, one-time cleanup of all existing stale keys was proposed. This involves directly removing the obsolete entries from the affected locale files. A community member had already prepared such a cleanup, demonstrating that it could resolve the validation failures across all 34 locales without altering any string values.

Maintaining pristine translation files is vital for ESHOPMAN's global reach and for developers integrating with the Admin API or building custom storefronts on HubSpot CMS. This discussion underscores the importance of community vigilance in refining the platform's core functionalities. By addressing issues like stale translation keys, we ensure that the ESHOPMAN Admin Hub remains intuitive and error-free for all users, regardless of their language.

What this means for ESHOPMAN Developers:

Developers working with ESHOPMAN's codebase, especially those contributing to the Admin Hub or building custom integrations, should be aware of this issue. When running localization validation, you might encounter numerous "Unexpected key" warnings. While a fix is in progress, understanding the underlying cause can help in debugging your own localization efforts. The command to validate your internationalization files looks like this:

yarn i18n:validate

This community insight serves as a call to action for continued collaboration to enhance ESHOPMAN's internationalization capabilities, making it an even more powerful and accessible headless commerce solution for the HubSpot ecosystem.