Files
jsonPrism/docs/RESX-MIGRATION.md
T
poli0981andClaude Opus 5.5 532b5cfd82 JSONPrism 2.0.0: Cloudflare Workers, TypeScript 7 and a full audit (#151)
- Web app moves to https://jsonprism.poli0981.dev on Cloudflare Workers
  (static assets + /api/turnstile/verify + /api/health), with security
  headers, redirects for the old /jsonPrism paths, previews for
  non-production branches and a production smoke workflow. GitHub Pages
  only redirects now.
- Web-only Turnstile human check (server-verified, 7-day pass) and
  cookieless Web Analytics (after consent, opt-out, off under GPC);
  Privacy Policy and Terms 2.0, consent version 2.
- Node 26, TypeScript 7 with the TS 6 API alias for typescript-eslint,
  dependencies on current majors (ends the ERESOLVE that kept main red).
- Converter fixes: CSV columns, binary ZIP entries, MySQL backslash
  escaping, RESX/XML validity, BSON size, YAML quoting and alias limits,
  TOML nulls and big integers, JSON error positions, JSONL/BOM linting.
- Web Worker conversion, faster editor, technical UI refresh with an
  Appearance menu and custom scrollbars, accessibility and i18n gaps.
- Tauri least-privilege capabilities, hardened CSP, Tauri 2.12.
- CI: SHA-pinned least-privilege workflows, SonarQube Cloud, Rust job,
  verifiable releases (SHA256SUMS + provenance); Dependabot grouping.
- 864 tests (97% line coverage), SonarCloud quality gate passing; docs,
  legal and CLAUDE.md refreshed.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-10-22 23:05:14 +07:00

9.1 KiB

Migrating i18next JSON to .NET RESX

This guide walks you through converting i18next-style locale files (used by JSONPrism's frontend, YTDescGen, the F2P Tracker, and most React projects) into .NET RESX resource files (used by AutoClickForge, PhantomMAC, and other WPF / Avalonia / WinForms projects).

It's the canonical workflow for keeping a single source-of-truth translation across your web and desktop projects.


The problem

Most JS/TS projects ship translations as namespaced JSON:

{
  "app": {
    "name": "PhantomMAC",
    "tagline": "Randomize your MAC address"
  },
  "buttons": {
    "ok": "OK",
    "cancel": "Cancel"
  }
}

.NET projects expect RESX:

<data name="app.name" xml:space="preserve">
  <value>PhantomMAC</value>
</data>
<data name="buttons.ok" xml:space="preserve">
  <value>OK</value>
</data>

Two mismatches:

  1. Shape: i18next allows arbitrary nesting; RESX requires a flat string-to-string map.
  2. Key convention: web typically uses dot.separated.paths already; native .NET sometimes uses PascalCase. JSONPrism doesn't impose either — preserve whatever you have.

Step 1 — Flatten nested JSON

JSONPrism's RESX converter rejects nested objects by design (RESX has no concept of nesting). You need a flat object first.

If your translations are nested, flatten them with a one-liner. Save this as flatten.mjs:

import { readFileSync, writeFileSync } from 'node:fs';

function flatten(obj, prefix = '', out = {}) {
  for (const [k, v] of Object.entries(obj)) {
    const key = prefix ? `${prefix}.${k}` : k;
    if (v !== null && typeof v === 'object' && !Array.isArray(v)) {
      flatten(v, key, out);
    } else {
      out[key] = typeof v === 'string' ? v : JSON.stringify(v);
    }
  }
  return out;
}

const input = JSON.parse(readFileSync(process.argv[2], 'utf8'));
writeFileSync(process.argv[3], JSON.stringify(flatten(input), null, 2));
console.log(`Flattened to ${process.argv[3]}`);

Run it:

node flatten.mjs strings.en.json strings.en.flat.json
node flatten.mjs strings.vi.json strings.vi.flat.json

You now have flat objects like:

{
  "app.name": "PhantomMAC",
  "app.tagline": "Randomize your MAC address",
  "buttons.ok": "OK",
  "buttons.cancel": "Cancel"
}

Step 2 — Convert to RESX with JSONPrism

Option A — Single file via the web UI

  1. Open JSONPrism (web or desktop)
  2. Drop or paste strings.en.flat.json into the input panel
  3. The format picker highlights RESX (a flat object is its native shape)
  4. Click RESX
  5. (Optional) Open the settings panel — enable Sort entries alphabetically if you want stable diffs (ordinal order, so the result is the same on every machine)
  6. Click Download → you get output.resx
  7. Rename to match your .NET project convention, e.g. Strings.resx or Resources.resx

Option B — Batch convert all locales at once

  1. Drop all your flattened locale files into the input area at the same time (2+ files automatically open the batch panel)
  2. Pick RESX in the format picker
  3. Click Process in the batch panel
  4. Click Download .zip

The output zip contains one .resx per input file, with the locale segment preserved:

strings.en.flat.json  →  strings.en.flat.resx
strings.vi.flat.json  →  strings.vi.flat.resx
strings.ja.flat.json  →  strings.ja.flat.resx

Rename to the .NET convention Resources.en.resx, Resources.vi.resx, etc. before dropping into your project.


Step 3 — Verify in Visual Studio

  1. Drop the generated .resx into your .NET project's resources folder

  2. Open in Visual Studio — the .resx editor should display every key/value as a flat table

  3. Build the project — if VS regenerates a Resources.Designer.cs automatically, you'll have strongly-typed access:

    var greeting = Resources.app_name; // "PhantomMAC"
    

    The default tooling replaces . with _ in the property name.

  4. Round-trip check: save the file from Visual Studio's editor; the diff against JSONPrism's output should be minimal (whitespace at most). If you see structural diffs, file an issue with the input JSON.


Adding comments

If your translators need context, use the { value, _comment } shape:

{
  "app.name": "PhantomMAC",
  "buttons.ok": { "value": "OK", "_comment": "Confirmation dialog primary action" }
}

JSONPrism emits both <value> and <comment> elements. The comment column shows up in Visual Studio's .resx editor and is preserved through ResXResourceWriter.

Change the comment key in the settings panel if your convention is different (e.g. note, description).


Round-trip safety notes

  • Special characters: &, <, > are XML-escaped automatically in values; " is also escaped in name= attributes. You don't need to pre-escape.
  • Line endings: a carriage return is written as &#xD;, so CRLF text survives a round trip (XML parsers would otherwise turn CRLF into LF). In name= attributes, tabs and line breaks are encoded as well.
  • Control characters: characters XML 1.0 cannot carry at all (C0 controls other than tab, LF and CR, plus U+FFFE / U+FFFF) are replaced with U+FFFD.
  • Whitespace: <data> elements get xml:space="preserve", so leading/trailing spaces in values survive — in both directions.
  • Empty values: null and undefined in JSON become empty <value></value> elements.
  • Numbers and booleans: coerced to their string representation (true, false, 42). If you want explicit nullability, wrap in a string in your source JSON.
  • Schema header: JSONPrism emits the standard RESX 2.0 schema. Visual Studio expects this — leave the Include xsd:schema header option on unless you're diffing manually. Turning it off drops only the xsd:schema block: the four <resheader> entries (resmimetype, version, reader, writer) are always written, because ResXResourceReader needs them.

Reverse direction (RESX → JSON)

JSONPrism converts RESX back to JSON (since v1.1.0). Switch the direction toggle to → JSON, pick RESX, then paste or open a .resx — or drop several .resx files into the batch panel to get a .zip of .json files.

  • Each <data name="…"> becomes a key, and its <value> the string value.
  • An entry with a <comment> becomes { "value": "…", "_comment": "…" }, using the comment key from the settings panel — the same shape the forward direction accepts.
  • Values always stay strings: "007", "1.10" and padded text come back exactly as written. (Before 2.0.0, "007" came back as the number 7.)
  • &#xD; is decoded back to a carriage return, so CRLF text round-trips.
  • The input must be well-formed XML with a <root> element; otherwise you get an error with its line and column. Files that declare a <!DOCTYPE> are rejected: RESX never uses one, and refusing it rules out entity-expansion ("billion laughs") documents.
  • <resheader>, <metadata> and <assembly> elements and the type / mimetype attributes are ignored, so typed (non-string) resources come back as their raw <value> text.

If you need typed resources resolved, or want to script the conversion outside JSONPrism, a small .NET console app using ResXResourceReader does it:

using System.Resources;
using System.Text.Json;

var dict = new Dictionary<string, string>();
using var reader = new ResXResourceReader("Resources.en.resx");
foreach (System.Collections.DictionaryEntry entry in reader)
{
    dict[(string)entry.Key] = entry.Value?.ToString() ?? "";
}
File.WriteAllText("strings.en.flat.json", JsonSerializer.Serialize(dict, new JsonSerializerOptions { WriteIndented = true }));

Run once after editing in Visual Studio's editor, then your JS project sees the changes.


CI integration sketch

If you maintain translations in strings.*.json and your .NET project under the same monorepo:

# .github/workflows/sync-resx.yml
name: Sync RESX from JSON

on:
  push:
    paths:
      - 'locales/strings.*.json'

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: 22.x
      - name: Flatten locales
        run: |
          for f in locales/strings.*.json; do
            node scripts/flatten.mjs "$f" "$f.flat"
          done
      # Then either:
      # a) use a CLI build of JSONPrism (a "Beyond" idea in docs/ROADMAP.md), or
      # b) commit the .flat.json and have a separate workflow open JSONPrism manually

A CLI version of JSONPrism is on the "Beyond" wishlist in docs/ROADMAP.md. Until then, batch through the web/desktop UI manually when locales change.


Worked example: PhantomMAC

PhantomMAC has 30+ locale files maintained as .resx originally. Going forward:

  1. Maintain the canonical source as JSON (easier for translators using web tools like Crowdin or Lokalise)
  2. On release, flatten + batch-convert through JSONPrism into Resources.<locale>.resx
  3. Drop into the .NET project, commit
  4. Visual Studio rebuilds the strongly-typed Resources.Designer.cs

The same approach works for AutoClickForge (~85 files, EN/VI) and any future MVVM project you scaffold.