Day number needs to be localized

[ortolot]

Hello,

I had a quick look at datify and datify-core, and I wonder if I have not found an issue that, to be fixed, would unfortunately require a significant rework of both packages…

In French, when writing a date in any litteral format, the first day of a month is always written in ordinal form, that is 1#super[er]. Just like 1#super[st] in English, except this ordinal form is not an option. And this is only the case for the first day of a month: all other days are written in regular (cardinal) form, with just numbers.

Since this is not an option, current datify is unfortunately not usable in French, as it produces things such as custom-date-format(datetime(year: 2025, month: 1, day: 1), lang: "fr") => "1 janvier 2025" which will be detected as a mistake by any fluent reader.

I am not sure of how that could be fixed. We would need some kind of possible localization of day numbers, and a partial localization too, since it would be tedious to specify all 31 possible numbers…

[Jeomhps]

Hey (Salut !),

I'm French too, and honestly, I haven’t written out dates by hand in a long time, so I didn’t notice this detail. You’re right—when writing a date in full in French, it should be “1er” (like “1er janvier”), and in English, it’s “1st.” But CLDR, which datify-core uses, doesn’t include this in its date formatting. Most libraries like Babel just use the regular numbers (cardinal form) for dates, which is why you see this issue.

CLDR does provide ordinal numbers, but they’re included as a separate, massive dataset and aren’t tied to dates directly. Since very few locales actually use ordinals in date formats, it makes more sense to handle these exceptions by hand, and maybe rely on the community to add more cases as needed.

I think adding this feature would be nice, but for now, I don’t think it belongs in datify-core, since it’s just an API that provides data and not formatting. The wrapper (datify) could add it, though. The tricky part is that you can’t just make a general rule like “use ordinal if day is 1 and the format is full,” because most languages don’t use ordinals for dates and it could break things.

I’ve followed the approach of packages like Babel in Python, which always use cardinal numbers for dates—never ordinals. So I believe the default behavior should be cardinal, and only switch to ordinal if an option is enabled. That way, if someone formats a date without knowing all the grammar rules for a language, they won’t make a mistake. For French, both “1 janvier” and “1er janvier” are correct, but “1er janvier” is the more formal way and not everyone knows that. So having cardinal as the default is safe, but it means people might miss the formal version.

On the other hand, since Typst is meant for writing documents, maybe it does make sense to make the formal ordinal style the default, and let users opt out if they want. Other projects and CLDR stick to cardinal by default because it’s safe and works for all languages, but the use-case in Typst is a bit different.

So, there are a lot of questions: Should we check the locale directly and apply ordinal only when it fits, or should we use a token or a boolean toggle for users to choose? For now, if you want “1er janvier 2025,” you can do:
custom-date-format(datetime(year: 2025, month: 1, day: 1), lang: "fr", pattern: "d'er' MMMM yyyy")
This works in datify because you can escape tokens with quotes and write anything you want, but it only helps if you know the rules and the date—it's not practical for automated dates (datetime.today()) or if you’re unfamiliar with the language.

What are your thoughts on that?

[ortolot]

Hello,

Thanks for the quick response ! Are you certain that it correct to write something like « le 1 janvier 1970 » ? When read literally, it is certainly not! Anyway, when requesting full or long format, it makes sense to use the ordinal form. If the user does not want something that is close to the oral, they have numeric forms for that.

One thing to consider is that the ordinal form should not be "1 janvier 1970" but [1#super[er] janvier 1970], which changes the return type. Therefore, I think a new function would be advised here. Something like custom-formatted-date() perhaps?

I manually did such a thing by post-processing custom-date-format()'s output, and I had to use an eval to do so. I wonder if if would be feasible without it.

[Jeomhps]

Hey, you’re right. In computer science, we usually avoid using ordinals because they are challenging to maintain and are often not necessary, especially in libraries that handle dates since those are mostly used for logs or similar tasks. However, Typst is a special case because it is designed for writing documents. In this context, using ordinals should probably be the default and the correct way to format dates.

You can technically output 1er janvier 1970 without using super and still have the er rendered on the top right by directly using the Unicode for superscript e, but it’s not practical, since not every letter has a Unicode superscript defined. It might work for French, but not for other cases. Outputting content has come up before, because with content I could use Typst’s #context to automatically use the user’s locale when none is specified, which would be nice.

So I’m not sure how to move forward. Maybe it’s a good idea to make a new function that outputs content and lets the user choose the format they want. Content would support more Typst features, while strings would give users more flexibility to manipulate the output.

Also, can you show me how you use eval to post-process functions? I’m having trouble understanding what eval does, so an example would help.

[ortolot]

Hello,

That usage of eval() is visible at https://github.com/Brndan/formalettre/blob/e14e415eed4a854f1bdbbbde36097c82af504fcc/src/lib.typ#L164.

This is a solution to the following problem:

• strings, can be modified with str.replace() but by definition, they do not contain typesetting information;
• content do contain typesetting information but cannot be modified in a simple way.

The idea is to first use string, in that case the return of datify.custom-date-format(), to replace stuff in it by Typst markup, typically .replace(regexp("^1 ", "1#super[er]"). Then, this string can be interpreted as Typst markup with the eval(it, mode: "markup"), that returns the corresponding content.