Skip to content

feat(drafting): draft enum values with their vocabulary terms - #230

Open
rue19 wants to merge 1 commit into
accordproject:mainfrom
rue19:feat/vocabulary-terms
Open

rue19 wants to merge 1 commit into
accordproject:mainfrom
rue19:feat/vocabulary-terms

Conversation

@rue19

@rue19 rue19 commented Nov 16, 2026

Copy link
Copy Markdown

Closes #10

Summary

draft() and TemplateMarkInterpreter.generate() now take a Concerto VocabularyManager and a locale. When both are given, each enum value is drafted as its term in that locale:

await processor.draft(data, 'markdown', { locale: 'fr', vocabularyManager });
// Trump: cœur.   (was: Trump: HEARTS.)

Terms replace values in variables and in {{#join}}, and inside list, optional and if blocks, nested ones included. The lookup goes from region to language (fr-CA, then fr, as VocabularyManager.getTerm already does), then to English, then to the raw value. Drafting without a vocabulary is unchanged.

Earlier work this builds on

This takes over #203 by @bhushan4work, which was closed after review, and follows that review's required changes item by item. Thanks for the groundwork, @bhushan4work: the locale fallback chain and the idea of handling {{#join}} come from #203.

  1. CI and TypeScriptRuntime.ts. I left TypeScriptRuntime.ts untouched. Its GenerationOptions is copied into generated template code (TypeScriptCompilationContext), and that code never sees a vocabulary. The interpreter declares its own GenerationOptions, the runtime options plus vocabularyManager, so nothing has to be kept in step and the code generator gains no import.
  2. No behaviour change without a vocabulary. draft() passes locale and vocabularyManager on only when a vocabulary is given, and otherwise passes exactly { now } as before. A test drafts {{#join}} with { locale: 'fr' } and no vocabulary, and asserts the output equals drafting with {} (HEARTS and SPADES, not et). All 46 existing snapshots pass unchanged.
  3. No labels. Terms replace enum values only. A test shows that a non-enum value (player) drafts unchanged even when the vocabulary has a term for its property.
  4. Blocks. For a variable, join, list, optional, if, and an optional nested in a list, there are two tests each. With a vocabulary, the term appears and the raw value doesn't. Without one, the raw value appears. Term lookup works in all of them, so no block needed a fix.

I also read #96 (the earlier vocabulary attempt), #217 (Duration and Period in the generation locale), which uses the same locale option but different code, and #216, whose open PRs #213 and #222 refactor this file. To keep a rebase onto those small, the change is one helper (enumTerm) plus a lookup before the existing drafting call at the three places a value is drafted. No existing function signature changes.

Flags

  • {{#foreach}} is not covered. It fails on main with or without a vocabulary (TypeError: property.isPrimitive is not a function), and TemplateMarkInterpreter.test.ts:55 already skips it as "currently broken". That's a separate bug, so I left it out of this PR. I'm happy to open an issue for it.
  • English as the last fallback. The review on fix: use vocabulary terms when generating text (#10) #203 asked to keep the fr-CA → fr → en chain, so a value with no term in the requested locale uses its English term before its raw identifier. AGENTS.md asks not to hardcode English. If you'd rather stop at the requested locale and draft the raw value, it's a one-line change, and the fallback test documents the current behaviour.
  • Where the vocabulary comes from. The caller supplies the VocabularyManager. cicero-core doesn't load vocabularies from a template archive yet (template-archive#711), so that would be a follow-up.
  • A vocabulary without a locale drafts the raw values, since there's no locale to look terms up in.

How I tested

  • npm test (licence check, lint, build, Jest): 211 passed (193 before, plus 18 in test/Vocabulary.test.ts), 46 snapshots unchanged, 0 lint errors.
  • npm run test:e2e: 6 passed.
  • Locales: fr, fr-CA (the vocabulary file declares fr-ca, the request uses fr-CA), en, and ja, whose list format differs from English (ハート、スペード).
  • Mutation check: forwarding locale without a vocabulary, dropping the {{#join}} lookup, and dropping the English fallback each make at least one test fail.

AI usage

I used an AI coding assistant for parts of this change. I reviewed, tested and can explain all of it.

Author Checklist

  • Ensure you provide a DCO sign-off for your commits using the --signoff option of git commit.
  • Vital features and changes captured in unit and/or integration tests
  • Commits messages follow AP format
  • Extend the documentation, if necessary
  • Merging to main from fork:branchname

draft() and TemplateMarkInterpreter.generate() take a Concerto
VocabularyManager and a locale, and draft each enum value as its term in
that locale: in variables, {{#join}}, and inside list, optional and if
blocks. The lookup falls back from a region to its language (as
VocabularyManager.getTerm does), then to English, then to the raw value.

Without a vocabulary, drafting is unchanged: draft() passes the locale on
only together with a vocabulary, since a locale alone would change how
{{#join}} formats lists. The vocabulary option is declared on the
interpreter, not in TypeScriptRuntime, whose GenerationOptions is copied
into generated template code.

Closes accordproject#10

Signed-off-by: rue19 <shrinjalik@gmail.com>
@rue19
rue19 requested a review from a team November 16, 2026 04:48
@mira-accord-project

Copy link
Copy Markdown
Contributor

Thank you for this, @rue19 — er, without the handle: thank you for opening this pull request, and for the careful write-up. Enum values drafted as their vocabulary terms, with the locale fallback and no change without a vocabulary, is the kind of change this repository needs.

What happens next: Dan Selman, who maintains this repository, has been asked to review it. The DCO check has passed. The other CI checks have not started yet, so a maintainer will need to approve them before they run. The review will come on this thread.

Your notes on the {{#foreach}} bug and the English fallback are useful, and they will be part of the review.


Posted automatically by Mira, an Accord Project agent. A maintainer will follow up; they make the decisions on this.

This branch has not been deployed

No deployments
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Use Vocabulary Terms

1 participant