Minimal JSON file format specific to Weblate

[lunikon]

We use Weblate quite extensively to manage the translation of our games and we and our volunteer translators are very happy with it. Our games are web-based, and since most web development these days happens for the client, our translation pipelines are dominated by formats used by react-intl/formatjs. And these work well: Formatjs generates stable keys based on description and default message (which provides the "context" functionality) and the format allows to add a description.

Beyond that, I also like the fact that JSON is a fairly simple, well-supported file format that strikes a good compromise between easy of processing and readability, in particular in semi-automated processes where these files aren't actually written by hand.

I mention this because I would like to move our legacy backend i18n as well as the localisation of documentation to similar formats and processes as well. I don't mind having custom processing steps on my end. For one they are often needed anyway (formatjs has an extract and a compile step), and they allow to add additional functionality which I might need anyway.

There's just one thing that I would love to have: A simple file format that's a minimal extension of the Format.JS JSON file format that allows me to set Weblate-specific information as additional keys on the entries. In particular, this is about check flags. This way, I would have fine-grained control over which strings might require Markdown format validation or which ones might require java-messageformat to be enabled because they are used in legacy parts of the app.

I am aware that there are ways to set this information in other ways, but to my knowledge, these either require separate components (I would have to cut component-specific source files) or elaborate processing configuration in Weblate (which lives outside of my repo and leads to implicit formatting conventions, like having the type of a string encoded in the message key or similar).

So my question/idea: Since there are plenty of JSON formats already and my suggestion would be a fairly small extension of an existing one, would it be possible to add a "Weblate JSON" format?

My discussion was primarily about flags, but of course, other Weblate-specifics could be encoded as well.

[tevinch]

If an extract/compile step is acceptable, an existing route is to keep the extended JSON as your authoring format and use PO as the interchange format in one Weblate component. The tradeoff is that Weblate still reads PO; this does not provide the proposed native JSON format.

Map the JSON key to msgctxt, defaultMessage to msgid, description to an extracted comment, and each entry’s flags to PO flags. For example, a Markdown entry gets #, md-text, while a legacy Java MessageFormat entry gets #, java-format. In the current version, java-format is the enabling flag for that check.

I put a small JSON ↔ PO example here, including source updates and compiling translated PO back to the original JSON record structure. Source updates use GNU msgmerge, followed by reapplying the JSON-owned flags: the tested gettext 0.22.5 drops custom md-text flags during merging. In the source-update example, the old translation and previous source are retained with fuzzy state; the compiler refuses that entry until reviewed.

The example was checked with Weblate 2026.10.1’s actual PO reader/save methods and Markdown/Java checks, including broken translations and missing-flags controls. Those are scripted file-format/check tests, without a Weblate database or UI session. If retaining PO in the repository is acceptable, this gives the per-string, repository-owned flags without splitting components or encoding conventions in message keys.

[michael-smt]

I don't feel like Weblate should be in the business of defining (yet another 😉) file format. Use gettext PO or XLIFF if you want full metadata support. They are the primary format of translate-toolkit which Weblate uses to serialize the different formats into a PO-like structure.

[nijel]

I would rather not invent yet another localization format; I believe there are far too many already existing.

What might make sense is to support parsing additional metadata from existing formats, similarly as we do with XML-based formats (see https://docs.weblate.org/en/latest/formats/xliff.html#xliff-flags). The framework handling these files would have to support such storage or ignore unknown fields in JSON.