JS Internationalisation using i18next

[alokdangre]

Discussion: Is Converting PO Files to JSON Using po2json the Right Approach for i18n?

Hi everyone,

I’ve been exploring ways to modernize our internationalization workflow and came across the [po2json](https://www.npmjs.com/package/po2json) npm package. My idea is to convert our existing PO files into JSON so that we can configure and use i18next (or a similar i18n library) more seamlessly.

My question is:
Is it correct to do this? Are there any potential pitfalls or concerns with using po2json to convert our PO files to JSON, or does this approach sound robust enough for our needs?

I’d appreciate any insights or experiences you have with this conversion process. Also, @walterbender, could you please share your thoughts on whether this is the right strategy for our project?

--- @walterbender

[walterbender]

We will need tools to make the conversion. (I have similar tools I already use to create the .INI file for webi10n.js.) And we still need to maintain the PO files themselves.

[alokdangre]

Subject: GSOC 2025 Plan – Modernizing JS Internationalization in Music Blocks

Hi @walterbender,

I hope you’re doing well. I’d like to work on the JS Internationalization project idea listed on the Sugar Labs ideas page. Although the idea is already present, I’m eager to contribute and have prepared a detailed strategy, research overview, and implementation plan. Below is my proposed approach:

---

1. Research & Background

Currently, our JavaScript activities rely on the somewhat antiquated webL10n.js library. This library lacks critical features—such as pluralization and locale-specific formatting—which modern applications require. My research has focused on:

• Evaluating Alternatives:
  Examining modern frameworks like i18next (and others such as FormatJS) with an eye toward advanced features, community support, and ease of integration with our existing workflow (which uses PO files).

• PO Files & Caching:
  Assessing how we can continue using our PO files while converting them to a JSON format at runtime. This approach will improve performance by caching translations instead of re-parsing PO files on every request.

• Integration Scenarios:
  Considering both server-side (e.g., in our Express-based backend for Music Blocks) and client-side implementation strategies, including dynamic locale switching and middleware integration.

---

2. Proposed Strategy

My strategy centers on maintaining our existing translation workflow (using PO files and a centralized localization.ini) while modernizing the runtime translation engine with i18next. The core components are:

• Centralized Configuration:
  Use localization.ini for defining:

  • defaultLocale
  • fallbackLocale
  • directory (location of PO files)

• Translation Files:
  Continue to manage translations in the /po directory, with one PO file per language.

• PO-to-JSON Conversion:
  Implement a mechanism to convert PO files to JSON. This JSON will be cached and loaded by i18next at runtime for improved performance.

• i18next Integration:

  • Initialize i18next using the configuration extracted from localization.ini.
  • Replace webL10n.js with i18next across our JS projects (starting with Music Blocks).
  • Support advanced i18n features (e.g., plurals, context-based formatting, interpolation).

---

3. Implementation Plan

Phase 1: Research and Framework Evaluation (≈25 hours)

• Deep dive into i18next features and confirm its compatibility with our PO files.
• Prototype a PO-to-JSON conversion module.
• Evaluate any alternative approaches if needed.

Phase 2: Planning and Design (≈25 hours)

• Finalize the integration approach.
• Document the overall workflow, including:
  • Parsing of localization.ini
  • Loading and converting PO files
  • Initializing and utilizing i18next in our codebase.
• Create architecture and data flow diagrams (see below).

Phase 3: Implementation (≈100 hours)

• Configuration Module:
  Develop a parser to read and process localization.ini.
• PO-to-JSON Converter:
  Implement or integrate a parser to convert PO files to JSON format, ensuring caching for performance.
• i18next Integration:
  Configure and initialize i18next with the parsed settings. Replace existing translation calls in Music Blocks.
• Middleware & Client-side Support:
  If applicable, integrate i18next as middleware in Express and set up dynamic locale switching.
• Testing:
  Ensure comprehensive testing, particularly for pluralization and locale-specific formatting.

Phase 4: Documentation and Finalization (≈25 hours)

• Update developer documentation to reflect the new internationalization workflow.
• Prepare guidelines/tutorials for maintaining translations.
• Final code reviews and performance optimizations.

---

4. Diagrams

Architecture Diagram

graph TD;
    A[localization.ini] --> B[Config Parser];
    B --> C[i18next Initialization];
    C --> D[PO File Loader];
    D --> E[PO-to-JSON Converter];
    E --> F[JSON Cache];
    F --> G[Runtime Translation Lookup];

Loading

[alokdangre]

I would appreciate your feedback on the following:

• Framework Selection:
  Do you agree that i18next is the optimal choice given our current constraints with PO files, or should we consider alternatives?

• Implementation Approach:
  Are there any potential pitfalls or enhancements you foresee with the proposed PO-to-JSON conversion and caching strategy?

• Additional Considerations:
  Are there any advanced features or best practices (e.g., enhanced caching, dynamic locale switching, integration with client-side frameworks) we should incorporate from the start?

@walterbender

[walterbender]

I am not sure that localization.ini is a good basis of any framework going forward as it is a lossy representation of the PO file content and it doesn't support language features such as plurals management.

[alokdangre]

Hi @walterbender,

Thanks for your feedback. I completely understand your concern about using localization.ini as a basis since it doesn't capture the full fidelity of the PO file content—especially regarding advanced language features like plural management.

My intent was to use localization.ini strictly as a configuration file to set global parameters (such as defaultLocale, fallbackLocale, and the location of our PO files) rather than as a source for translation data. The actual translation content—including plurals, context, and other language-specific details—would be fully parsed from the PO files and then converted to JSON. This JSON cache would be designed to retain all the necessary data for i18next to manage plurals and other language nuances.

That said, I see the value in exploring alternatives where we minimize any potential data loss. One possibility might be to either extend the configuration file to include more detailed language rules or to rely solely on the PO files for translations while using a separate configuration mechanism for global settings. I’m very open to suggestions on how best to achieve this while ensuring full support for language features.

I’d love to discuss this further to refine the approach. Thanks again for your guidance!