Skip to content

fix: draft Duration and Period in the generation locale - #217

Open
arshilkxwork wants to merge 4 commits into
accordproject:mainfrom
arshilkxwork:fix/duration-singular-unit
Open

arshilkxwork wants to merge 4 commits into
accordproject:mainfrom
arshilkxwork:fix/duration-singular-unit

Conversation

@arshilkxwork

@arshilkxwork arshilkxwork commented Oct 22, 2026 •

Copy link
Copy Markdown

Problem

A variable typed as org.accordproject.time@0.Duration or Period drafts as ${amount} ${unit} with the raw enum value. An amount of 1 comes out as "1 days", and a template written in another language still gets English units. The first version of this PR mapped the enum values to English singulars, which only helped English templates.

Fix

durationDrafter formats the amount with Intl.NumberFormat (style: 'unit', unitDisplay: 'long') in the locale generation option, and falls back to 'en' when no locale is set. CLDR data then picks the unit word, its plural form and the word order. With the examples from the review on #52:

locale amount 2, days
en 2 days
fr 2 jours
hu 2 nap
ar يومان
zh 2天

The drafter keeps a map from each TemporalUnit and PeriodUnit value to an Intl unit identifier (days to day). Those identifiers are the only unit names in the code.

Drafters returned by getDrafter take an optional third locale argument. The interpreter passes options.locale for variables. Inside {{#join}} the join's own locale takes precedence, the same rule joinList follows. The other drafters ignore the argument.

Digit grouping is off, so 1000 days still drafts as "1000 days".

Not covered

Intl has no unit for quarters, so quarters still drafts as "1 quarters" or "2 quarters" in every locale. Units outside the two enums also fall back to <amount> <unit>.

Template authors can't change the wording yet. That needs the template engine to load Concerto vocabularies, the larger piece of work discussed on #52.

Tests

test/DurationDrafter.test.ts covers the English singular for each enum unit Intl supports, amounts of -1 and 0, no digit grouping, output in fr, de, hu, ar and zh, the quarters fallback, and the locale passing through getDrafter. test/GenerateOptions.test.ts generates a template with a Duration and a Period using locale: 'en' and locale: 'fr'. The locale assertions compare with plain spaces: CLDR puts a no-break space before some French units, and the exact character can change between ICU versions.

npm test passes (216 tests) and npm run lint reports no errors.

The TemporalUnit and PeriodUnit enums in org.accordproject.time declare
their values in the plural (days, months, ...), and durationDrafter
appended the unit as-is, so { amount: 1, unit: 'days' } drafted as
"1 days". Map the enum values to their singular form when the amount is
1 or -1. Units outside the enums pass through unchanged.

Signed-off-by: arshil-khan <arshilkxwork@gmail.com>
@arshilkxwork
arshilkxwork requested a review from a team October 22, 2026 13:15
@mttrbrts-agent mttrbrts-agent added the bug Something isn't working label Nov 1, 2026
@mira-accord-project

Copy link
Copy Markdown
Contributor

Thank you for this contribution, and welcome to the Accord Project. Apologies for the wait.

I have approved the CI runs, which were waiting for approval, so you should see the Build and CodeQL results shortly. I have also asked a maintainer to review the change. If anything fails, please push a fix to this branch and we will take another look.

Drafted by an Accord Project agent, reviewed by a maintainer.

@mira-accord-project mira-accord-project Bot left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thank you for this fix, @arshilkxwork, and welcome to the project. Drafting "1 day" instead of "1 days" is a good improvement. The singular map covers every unit in TemporalUnit and PeriodUnit. Unknown units fall back to the original text, and the tests cover each unit, -1, 0 and an unknown unit. CI is green and the licence header is in place. I found nothing blocking. There is one optional nit below. The PR now needs a maintainer's review and approval before it can be merged.

Nothing blocking; some suggestions below. Findings: 1 nit.


Automated review by Mira, an Accord Project agent, at 46f1110. Findings are labelled blocking, should-fix or nit; a maintainer makes the final call.

if (!isDuration(value)) {
return '0 unknown';
}

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

nit · correctness

SINGULAR_UNITS is a plain object, so a unit string such as constructor or toString would resolve to an inherited Object.prototype member rather than falling back to value.unit. Real unit values come from the enums, so this is unlikely in practice. A Map<string, string>, or an Object.hasOwn(SINGULAR_UNITS, value.unit) check, would make the fallback robust. This is optional.

arshilkxwork added a commit to arshilkxwork/template-engine that referenced this pull request Nov 5, 2026
SINGULAR_UNITS was a plain object, so a unit such as 'toString' or
'constructor' resolved to an inherited Object.prototype member instead
of falling back to the unit as given. Use a Map, and test that those
keys draft unchanged.

Addresses review feedback on accordproject#217.

Signed-off-by: arshil-khan <arshilkxwork@gmail.com>

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01Rs7Nc4NXek5stCU9JxfPba
SINGULAR_UNITS was a plain object, so a unit such as 'toString' or
'constructor' resolved to an inherited Object.prototype member instead
of falling back to the unit as given. Use a Map, and test that those
keys draft unchanged.

Addresses review feedback on accordproject#217.

Signed-off-by: arshil-khan <arshilkxwork@gmail.com>
@arshilkxwork
arshilkxwork force-pushed the fix/duration-singular-unit branch from c152b6a to 3f62f49 Compare November 5, 2026 15:20
@arshilkxwork

Copy link
Copy Markdown
Author

AI disclosure (apologies for the late note): I'm sorry for not mentioning this earlier. I only just read the Accord Project AI Usage Policy, so I'm adding this disclosure right away.

I used Claude (Anthropic's AI assistant) while working on this PR, both for the original fix (46f1110) and for the follow-up commit addressing the review nit (3f62f49, which switches SINGULAR_UNITS to a Map and adds tests for prototype keys). The c152b6a commit referenced above was an earlier version of that follow-up. I force-pushed it away to drop the AI attribution lines from the commit message before I knew about the disclosure requirement, which I shouldn't have done.

I've reviewed and understand every change, and the full test suite passes locally (207 tests). I'll make sure to disclose AI use up front in future contributions.

@mttrbrts

mttrbrts commented Nov 5, 2026

Copy link
Copy Markdown
Member

Thanks for the contribution @arshilkxwork, you've found a real problem, but unfortunately the fix is much more involved that the solution here.

We shouldn't assume that templates are written in English, and so hardcoding those values here is the wrong solution. There is also a related problem that different languages manage plurals in different ways. Here is some more inspiration for the wider problem:

I'd be happy to draft a plan for this work if you'd like to take it on?

@github-actions github-actions Bot added the maintainer-engaged A maintainer has commented or reviewed this item label Nov 6, 2026
durationDrafter formats the amount with Intl.NumberFormat's unit style in
options.locale, or 'en' when it is unset, so CLDR data supplies the unit
word, its plural form and the word order. This replaces the table of
English singulars added earlier on this branch.

getDrafter passes the locale through to drafters. In a join, the join's
own locale takes precedence over the option, as it does in joinList.

Intl has no quarter unit, so quarters and any unit outside the
TemporalUnit and PeriodUnit enums still draft as "<amount> <enum value>".

Signed-off-by: arshil-khan <arshilkxwork@gmail.com>
@arshilkxwork arshilkxwork changed the title fix: use the singular unit when drafting a Duration or Period of 1 fix: draft Duration and Period in the generation locale Nov 6, 2026
@arshilkxwork

Copy link
Copy Markdown
Author

Thanks, that makes sense. I've reworked the PR so the drafter no longer contains English unit words. It formats through Intl.NumberFormat in the locale generation option, so CLDR handles the plural rules and word order, and the fr, hu, ar and zh examples from your table on #52 come out as listed there. Quarters still fall back to the enum value because Intl has no quarter unit.

That leaves vocabulary support open. I'd like to take it on if you're willing to draft the plan. I can keep this PR as a stopgap until then, or close it if you'd rather do it all in one change.

Comment thread src/TemplateMarkInterpreter.ts Outdated
const drafter = getDrafter(context.elementType);
context.text = joinList(arrayData.map(arrayItem => {
return drafter ? drafter(arrayItem, context.format) : arrayItem as string;
return drafter ? drafter(arrayItem, context.format, context.locale ? context.locale : options?.locale) : arrayItem as string;

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
return drafter ? drafter(arrayItem, context.format, context.locale ? context.locale : options?.locale) : arrayItem as string;
return drafter ? drafter(arrayItem, context.format, context.locale ?? options?.locale) : arrayItem as string;

Comment thread src/TemplateMarkInterpreter.ts Outdated
// we want to draft Enums as strings, not objects
const drafter = getDrafter(type && type.isEnum() ? 'String' : context.elementType);
context.value = drafter ? drafter(variableValue, context.format) : JSON.stringify(variableValue) as string;
context.value = drafter ? drafter(variableValue, context.format, options?.locale) : JSON.stringify(variableValue) as string;

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Help me to understand why the context.locale isn't relevant here?

Suggested change
context.value = drafter ? drafter(variableValue, context.format, options?.locale) : JSON.stringify(variableValue) as string;
context.value = drafter ? drafter(variableValue, context.format, context.locale ?? options?.locale) : JSON.stringify(variableValue) as string;

@mttrbrts mttrbrts left a comment

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This is a great stop-gap, just a couple of minor nits, otherwise I'm happy to approve. Thanks!

…tion

Pass context.locale ?? options?.locale to drafters for variables as well
as joins, so a locale on the node wins over the generation option wherever
one is set. TemplateMark only defines locale on JoinDefinition today, so
variables still draft in options.locale.

durationDrafter now treats an empty locale as unset and drafts in 'en',
because Intl.NumberFormat throws on ''. Before this change a join with
locale="" fell through to options.locale; with ?? it reaches the drafter.

Signed-off-by: arshil-khan <arshilkxwork@gmail.com>

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

ai/decision:needs-review ai/kind:bugfix ai/risk:medium bug Something isn't working maintainer-engaged A maintainer has commented or reviewed this item

Projects

None yet

Development

Successfully merging this pull request may close these issues.

3 participants