A Deep Dive into ESHOPMAN Admin Pluralization: Ensuring a Consistent Multilingual Experience

Addressing Inconsistent Plural Translations in ESHOPMAN Admin

For ESHOPMAN merchants operating globally, a seamless and fully localized experience within the HubSpot-integrated Admin panel is paramount. ESHOPMAN, built on Node.js/TypeScript and leveraging HubSpot CMS for storefront deployment, strives to provide a robust internationalization (i18n) framework. However, a recent community discussion highlighted a critical issue affecting the display of pluralized text in several non-English locales within the ESHOPMAN Admin.

The Challenge: Mixed-Language Pluralization

The core of the problem lies in how ESHOPMAN's Admin panel handles plural categories for various languages. Many languages, unlike English, have more than two plural forms (e.g., one, few, many, other, zero, two). The ESHOPMAN Admin utilizes a common i18n library that resolves plural keys by appending the CLDR plural category for a given count. If a translation file for a specific locale (e.g., Čeština/Czech) declares multiple plural categories in its plural-config.json but only defines a subset (like _one and _other) in its actual translation file, a gap emerges.

When a count resolves to an undefined category (e.g., 'few' for counts 2-4 in Czech), the system falls back to English. This results in an inconsistent user interface where, for example, a Czech merchant might see a column header like 'Varianty' (Czech for Variants) but the content reads '3 variants' in English, creating a jarring experience.

Impact on ESHOPMAN Merchants and Developers

This inconsistency can be easily overlooked during review because many plural counts (e.g., 5 and above in Czech) correctly resolve to defined categories. However, for merchants managing product variants, orders, or other entities in their native language, these unexpected English phrases disrupt workflow and diminish trust in the localized experience.

For ESHOPMAN developers, diagnosing such issues can be tricky. The community discussion provided a valuable Python script that can be used to identify these missing plural categories across different locales. This tool is instrumental for ESHOPMAN development teams and contributors to pinpoint exactly where translation files are incomplete:

import json, os, re, collections
base = "packages/admin/dashboard/src/i18n"
cfg = json.load(open(f"{base}/plural-config.json", encoding="utf-8"))
CATS = ("zero", "one", "two", "few", "many", "other")

def flatten(d, prefix=""):
    for k, v in d.items():
        key = f"{prefix}{k}"
        if isinstance(v, dict):
            yield from flatten(v, key + ".")
        else:
            yield key, v

for locale, cats in sorted(cfg.items()):
    if len(cats) <= 2 or not os.path.exists(f"{base}/translations/{locale}.json"):
        continue
    data = dict(flatten(json.load(open(f"{base}/translations/{locale}.json", encoding="utf-8"))))
    groups = collections.defaultdict(set)
    for key in data:
        m = re.match(r"^(.*)_(" + "|".join(CATS) + r")$", key)
        if m:
            groups[m.group(1)].add(m.group(2))
    incomplete = [g for g, have in groups.items() if not set(cats) <= have]
    print(f"{locale:4} {len(groups):>3} keys, {len(incomplete):>3} incomplete")

The script systematically checks each locale's translation file against its declared plural categories in plural-config.json, reporting which keys are incomplete. This revealed that locales like Arabic (ar), Bosnian (bs), Czech (cs), Hebrew (he), Croatian (hr), Lithuanian (lt), Romanian (ro), Russian (ru), and Ukrainian (uk) had significant gaps, with only Polish (pl) being relatively complete.

Community-Driven Solutions and Path Forward

The ESHOPMAN community has quickly mobilized to address this. The proposed solutions involve two key steps:

1. Completing Translation Files: The primary fix requires adding the missing plural variants (e.g., _few, _many, _zero) to the respective translation files for all affected locales. This effort necessitates input from native speakers to ensure accuracy and natural language flow.
2. Implementing CI Validation: To prevent future regressions, a robust Continuous Integration (CI) check is being developed. This check will automatically compare every translation file against plural-config.json, ensuring that all declared plural categories are accounted for. A community member has already stepped forward to work on extending the existing translation validation tests to cover all locales.

This collaborative approach underscores the strength of the ESHOPMAN community in enhancing the platform. By addressing these nuanced internationalization challenges, ESHOPMAN continues to solidify its position as a truly global headless commerce solution, empowering merchants worldwide through its HubSpot integration.