Ensuring Translation Integrity: Resolving Stale Language Keys in the ESHOPMAN Admin Dashboard

Maintaining ESHOPMAN's Global Reach: Addressing Translation File Integrity

At Move My Store, we understand that a robust e-commerce platform like ESHOPMAN thrives on its ability to support merchants globally. A key component of this global reach is effective internationalization (i18n), ensuring that the ESHOPMAN Admin Dashboard—your central hub for storefront management within HubSpot—is accessible and accurate in multiple languages. Recently, our vibrant ESHOPMAN community identified a crucial issue related to translation file integrity, highlighting the importance of meticulous maintenance in a headless commerce environment built on Node.js/TypeScript.

The Challenge: Stale Keys in ESHOPMAN Admin Dashboard Translations

A community member reported a specific bug concerning the Persian translation file (fa.json) within the ESHOPMAN Admin Dashboard. The issue surfaced during a routine validation check, where the platform's internationalization script, yarn i18n:validate, failed. The core problem was the presence of "stale" keys in fa.json—translation entries that no longer had corresponding keys in the primary English translation file (en.json).

This validation failure was critical because the ESHOPMAN Admin Dashboard's translation JSON schema is configured with additionalProperties: false. This strict setting ensures that all keys in any translation file must exist in the primary language file, preventing orphaned or outdated entries. When the script encountered these stale keys, it reported an error: must NOT have additional properties for each offending entry.

Specifics of the Stale Keys:

• Renamed Search Group Keys: Fifteen keys under app.search.groups.* (e.g., app.search.groups.customerGroup, productVariant, priceList, taxRegion, salesChannel) had been renamed from camelCase to snake_case in en.json. However, their older camelCase forms persisted in fa.json.
• Removed Tax-Related Keys: Three specific tax-related keys—taxRegions.create.errors.rateIsRequired, taxRegions.create.errors.nameIsRequired, and taxes.taxRate.editTaxRate—had been entirely removed from en.json but remained in fa.json.

While these stale keys did not directly impact runtime functionality (as the i18next library used by ESHOPMAN only looks up keys present in the primary English file), their presence caused the vital validation script to fail, disrupting the development and build process for the ESHOPMAN Admin Dashboard.

Reproducing the Validation Error

For developers working with ESHOPMAN's Node.js/TypeScript codebase, reproducing this issue was straightforward:

1. Ensure you are working with the latest development branch of the ESHOPMAN Admin Dashboard.
2. Run yarn install to set up dependencies.
3. Navigate to the Admin Dashboard package directory.
4. Execute the validation command:

   yarn i18n:validate fa.json

This command would then exit with an error code, listing each of the 18 additional properties that violated the schema.

The ESHOPMAN Community Solution: A Clean Sweep

The proposed solution, quickly adopted by the ESHOPMAN development team, was elegantly simple: remove the 18 obsolete keys from the fa.json file. This action did not change any existing Persian translation values nor did it require adding any new keys. It was purely a cleanup operation to align fa.json with the current structure of en.json, thereby satisfying the strict validation schema.

This incident underscores a crucial best practice for maintaining any complex software, especially a headless commerce platform like ESHOPMAN that integrates deeply with HubSpot CMS for storefront deployment. Regular validation and synchronization of internationalization files are essential to ensure a smooth development workflow and a consistent user experience for merchants managing their stores in various languages.

The ESHOPMAN community's proactive identification and resolution of such issues are vital. It ensures that the platform remains robust, scalable, and developer-friendly, continually enhancing the experience for all users leveraging ESHOPMAN for their e-commerce needs within the HubSpot ecosystem.