Multiple JSON files

Where each file lands

The name is the file name without its extension. A name that is nothing but a locale code is the language's own file rather than a name someone chose, so it goes to the default file:

de.json, de-DE.arb and pt_BR.json are all read as locale codes. de-final.json is not one, so it is taken as a name.

Correcting the guess

In multi-file mode the derived name is an editable field on every row, so a guess can be corrected before the import rather than undone after it. Names take letters, digits, dot, hyphen and underscore, up to 255 characters — checked in the dialog, because the import sends one request per file and a name the server rejects would otherwise fail one file after the others had already landed.

Two files that resolve to the same name are refused before anything is written, and both file names are shown. In one-file mode there is no column and no choice: one import writes one file of one language, so picking more than one file is refused outright.

One preview per file

The second step previews each file on its own — new keys, conflicts with the values already there, keys the import will skip, the unchanged count and any ARB metadata changes. Per file rather than per import, because every file has its own keys and therefore its own conflicts.

Conflict handling, ARB metadata and the round-trip of context notes are the same for one file as for twenty — Import & Export covers them.

The file filter

The filter sits in the editor's ⋮ menu and offers All files or one file, each with its key count; the menu carries a dot while a single file is selected. With All files selected the key tree is grouped into one collapsible section per file, so the files stay visible instead of being flattened into one list.

The badge

A key outside the default file carries that file's name beside it. Two keys can share a leaf name and differ only by the file they live in — that is the whole reason the badge exists. Inside a grouped section the heading already names the file, so the badge is not repeated on every row.

Creating a key

Start typing a key and Mergua suggests the files whose name the first segment matches. Type a segment that matches no existing file and it says so before you commit — the key would create a new JSON file.

What you get

The archive keeps the layout your app already reads — one folder per locale, one file per name — so it unpacks straight over your i18n directory.

XLIFF keeps the files inside one document

The table above is the JSON and ARB story. An XLIFF download of All files is not an archive: a file is a <file original="common.json"> element inside the one document, in the order the picker lists them. So one language hands over as one fr.xlf however many files it is split across, and a translator opens one thing.

Coming back the other way it is one file per upload, and this is the one place the two directions differ. An import writes one file, so a document holding several <file> elements is refused by name rather than merged into one or fanned out across them — including the All-files document Mergua wrote. Hand that one over; bring the translations back a file at a time, picking each in the download dialog. A single-file document names its own: original is read and proposed, so you do not pick it twice.

Branches bring their own files

The list is the selected target's, not the project's: a branch can hold a file that exists nowhere on main, and main's key counts say nothing about that branch. Switching the target reloads the list, and a file the previous target had but the new one does not falls back rather than downloading nothing.

Over the API

The download endpoints take one file at a time through ?namespace=, defaulting to default. There is no "all files" over the API — the archive is assembled in the browser, so ask for the files you want one request each, or let the CLI walk them for you.

curl -H "X-API-Key: $MERGUA_API_KEY" \
  "https://api.mergua.com/v1/$PROJECT_ID/translations/fr?namespace=common"

Every parameter these endpoints take is listed under API access.

Rename

common becomes shared and every key keeps its identity — its translations, its history, its comments and any branch work on it come along untouched. Nothing is created and nothing is copied, so branches need no reconciling: the keys are the same keys, under a different file.

A name already in use is refused rather than absorbed — a rename that quietly became a merge would settle same-named keys without anyone deciding. Merge instead. A name held only by deleted keys is refused too, and says so: delete that file first to free it.

Merge

Moves the keys of one file into another. Keys only one file holds simply change file. Keys both hold are conflicts, and the merge does not run until you choose:

• Keep the version in the target — the source's key is deleted and the target's value stands.
• Use the version from the source — its values are written onto the target's key, recorded in that key's history the way any edit is, and the source's key is then deleted.

Either answer keeps the target's key, so its history and comments stay attached to the key that survives. The dialog shows how many keys move and which ones clash before you confirm.

A merge is refused while an open branch still holds pending changes on one of the clashing keys — merge or discard that branch first. The message names it.

Delete

Only a file that holds no keys any more, which is what a merge leaves behind. Deleting it frees the name and removes the file's already-deleted keys for good — they are what was still holding the name. A file that still holds keys says how many, and points at merge.