Give each unlisted language its own ISO 639-3 code (qaa..qtz)

[hatton]

Problem

An archive (ELAR) cannot ingest IMDI files that lameta 3.0.x writes. For a language that ISO 639-3 does not list, lameta wrote the whole tag into the IMDI language id, for example <Id>ISO639-3:qaa-x-Kürbinian</Id>, where only a 3-letter code belongs. It also gave every such language the same code, qaa, so an archive could not tell two invented languages apart. lameta V2 let the user type a code and a name, and it exported ISO639-3:qab, which is what the archive expects.

Cause

In V2 the Subject Language field had type: "language", and the editor was a dialog with a Language Code box and a Name box. V3 changed the field to type: "languageChoices", and no field uses type: "language" any more, so that dialog became unreachable. The new type-ahead editor built qaa-x-<name> unconditionally, and the two IMDI emitters for a session language and an actor language passed the tag through without reducing it to a code.

What this PR changes

• A new module, src/languageFinder/privateUseLanguages.ts, allocates the next unused code from qaa..qtz for each new language, and resolves a collision in an old project deterministically at export time. No project file is rewritten.
• A new dialog, Add an Unlisted Language, takes a name and a code, validates the code against the qaa..qtz range and against the codes the project already uses, and refuses a name that holds a semicolon or a colon. It replaces a window.alert that only announced what had already happened.
• An unlisted language can be created only in Subject Languages on the Project tab, the one field whose definition carries canCreateNew. Two end-to-end tests hold that gate shut, because losing it would let two sessions each be given qaa.
• Typing a free code such as qax now opens that dialog, instead of silently adding a nameless language. Typing a name that no language matches opens it too.
• No field offers a code from the range that has no name of its own, so typing qa or unlisted no longer produces an anonymous qaa.
• IMDI now writes the primary subtag at every language id, and a real name beside it: <Id>ISO639-3:qab</Id><Name>Tolo</Name>. Four metadata-language sites that bypassed the conversion now use it.
• The language picker's menu renders in document.body. Several ancestor panes have overflow: hidden, and on the short Session and Person fields they cut off the whole dropdown, so those fields appeared to have no type-ahead at all.
• The code beside a language name is now legible. The highlight colour is the lameta dark blue, and the code reads at 4.9:1 contrast, which passes WCAG AA.
• Serialization keeps a name the file already carried, so dragging a pill no longer turns qab-x-tolo:Tolo into qab-x-tolo.
• The PO catalog generator now escapes quotes. A field description holding a quote used to truncate its entry and leave stray tokens behind.
• New unit tests for the allocator, the parser, the serializer, the catalogs and the IMDI output, and 12 end-to-end tests for the picker and the dialog. The localization catalogs hold the new strings.

---

Devin review

[hatton]

[Claude Opus 5 from Hatton's machine during preflight]

Consulted Devin on 2026-08-27 up to commit 6f9e746f400538215199f8ebdd83ba5cd0a62e62.

Two rounds. Round 1 ran against 29256f01 and found 1 non-severe bug and 4 flags, 1 of them an Investigate flag. Both items that were actionable are fixed in 6f9e746f, and Devin's round 2 marks each of them resolved:

• Bug, Unescaped quotes in a catalog string (locale/en/fields.po:242) - fixed. The cause was archive-configurations/extractFromJSON.ts, which interpolated a field description into a PO string with no escaping, so it had broken a second entry as well. The generator now escapes, the catalogs are regenerated, and archive-configurations/poEscaping.spec.ts refuses any malformed string. Devin: "The generated catalog now escapes the embedded quotation marks in this entry."
• Flag, Session language Name bypasses nameForExport - fixed. Both session language paths now call nameForExport. Devin: "unknown private-use tags no longer reach IMDI Name elements unchanged."

One Investigate flag stands, mirrored as a review thread above: Session-only invented languages fall outside the collision map. Confirmed real, and on the preflight decision report, because it reopens an allocation-scope decision that the plan settled.

Three informational flags, assessed, no action:

• getIso639_3Code now returns only the primary subtag. Intended, and the point of the change. Only two callers exist, Imdi-static-fns.ts:134 and ImdiGenerator.ts:174, both IMDI. No RO-Crate or PARADISEC path calls it, so no BCP 47 output loses its script or region subtag.
• Picker filter depends on two accessors agreeing. The case needs a finder built with a private-use default and an empty project-language accessor, which only a test constructs.
• Debounced loader captures first-render languageFinder. Devin agrees the change is correct. The finder reference does not change without a remount.

[hatton]

[Claude Opus 5 from Hatton's machine during preflight]

Consulted Devin on 2026-08-27 up to commit 27f3c5db1f935c77b2f46ef839408a9084a73ad2.

Round three. No new actionable finding. Both earlier actionable items stay marked resolved by Devin: the unescaped quotes in the catalog, and the session Name that bypassed nameForExport.

Devin repeats the Investigate flag Session-only invented languages fall outside the collision map. Its thread above now carries the answer and is resolved: a user cannot create an unlisted language outside the Project tab, so every invented language is in a project language field and therefore in the collision map. Commit 27f3c5db adds two end-to-end tests that hold that gate shut.

One new informational flag, Names preserved for languages the file already carried. It notes that serializeLanguageFieldValue now writes eng:English where it once wrote eng, for an entry whose file already carried the name. That is intended, and languageTagFieldValue.spec.ts covers it. No action.

[HughP]

Hi John, @hatton

Semantically, the iso 639 identifier “und” is the appropriate identifier here not “qaa” or any other identifier in the reserved/“special use” block. The use of the ‘-x-‘ construct is a BCP-47 convention and not an iso 639 thing so <Id>ISO639-3:qaa-x-Kürbinian</Id> is not accurate. This is a constructed BCP-47 tag not an ISO 639 identifier. Additionally, the component that follows the -x- needs to conform to the BCP-47 convention, which it doesn’t. There are length and character set restrictions.