datify-core

Datify-core is an API library that provides foundational localization data and patterns to format dates, powered directly by Unicode CLDR data (cldr-json) and designed for Typst. It is the backend for Datify, but is reusable in any Typst project needing localized month and day names or locale-specific date patterns.

If you need high-quality, up-to-date, and standards-based date strings for any supported language, whether for a date formatting tool, localization system, or any Typst workflow, datify-core is your solution.

Data quality:
All locale data is sourced from cldr-json, which only includes CLDR data that has achieved draft="contributed" or draft="approved" status. This is the same threshold used by ICU (International Components for Unicode), ensuring high reliability and coverage.

---

Table of Contents

• Features
• Installation
• API Reference
  • get-day-name
  • get-month-name
  • get-date-pattern
• Supported Locales
• Community Overlay
• Testing
• Contributing
• License
• Credits

---

Features

• CLDR-sourced data: Day names, month names, and date patterns for hundreds of locales (languages and regional variants), generated directly from the Unicode CLDR.
• Simple API: Look up day/month names and date patterns by locale, usage, and width.
• Locale fallback: Unknown or region-specific codes resolve via the CLDR truncation chain (e.g. fr-CA → fr), ultimately falling back to the default locale (en), so a lookup never fails on an unrecognized locale.
• Reproducible & auto-updated: The data is pinned to an exact cldr-dates-full version and regenerated by a single tool; a scheduled job opens a PR when a newer CLDR release is available.
• Reusable: Designed for Datify, but works in any Typst project.

---

Installation

Install with Typst’s package manager or from preview:

#import "@preview/datify-core:2.1.0": *

(Replace version as needed.)

---

API Reference

get-day-name

Get the localized name of a weekday.

Parameters:

Name	Type	Description	Default
weekday	int/str	The weekday (1–7, or "1"-"7")	required
lang	str	Locale code, e.g. "en", "fr"	"en"
usage	str	"stand-alone" (calendar headers) or "format" (full date formatting)	"stand-alone"
width	str	"wide", "abbreviated", "narrow"	"wide"
community	bool	Consult the opt-in community overlay first	false

Example:

#get-day-name(1, lang: "fr", usage: "stand-alone", width: "wide") // lundi
#get-day-name(7, lang: "en", usage: "format", width: "abbreviated") // Sun

---

get-month-name

Get the localized name of a month.

Parameters:

Name	Type	Description	Default
month	int/str	The month (1–12, or "1"-"12")	required
lang	str	Locale code, e.g. "en", "fr"	"en"
usage	str	"stand-alone" (calendar headers) or "format" (full date formatting)	"stand-alone"
width	str	"wide", "abbreviated", "narrow"	"wide"
community	bool	Consult the opt-in community overlay first	false

Example:

#get-month-name(2, lang: "en", usage: "format", width: "abbreviated") // Feb
#get-month-name(8, lang: "de", usage: "stand-alone", width: "wide") // August

---

get-date-pattern

Get the date formatting pattern for a given locale.

Parameters:

Name	Type	Description	Default
pattern-type	str	"full", "long", "medium", "short"	required
lang	str	Locale code, e.g. "en", "fr"	"en"
community	bool	Consult the opt-in community overlay first	false

Example:

#get-date-pattern("medium", lang: "de") // dd.MM.y

---

Supported Locales

datify-core ships CLDR data for 765 locales — day names, month names, and date
patterns. Each locale stores only the values that are genuinely localized; any
value a locale does not define is resolved through the CLDR fallback chain to its
parent locale and ultimately to the default locale (en), so every supported
locale returns sensible output. The full list is in
src/translations/index.toml.

---

Community Overlay

CLDR is the single source of truth, but some locales have regional conventions
or styling that CLDR doesn't carry. Those live in an opt-in overlay under
src/translations/community/, which is hand-maintained and never touched by the
generator (so it survives the monthly regeneration).

Pass community: true to consult it. When enabled, a lookup tries the overlay
first (resolved by the same truncation rule), and any cell the overlay doesn't
define falls through to CLDR. With community: false (the default), behavior is
pure CLDR.

// CLDR (default)
#get-day-name(1, lang: "pt-BR", usage: "format", width: "narrow") // S
// With the overlay (Brazilian numbered narrow weekday)
#get-day-name(1, lang: "pt-BR", usage: "format", width: "narrow", community: true) // 2ª

The overlay holds only data that genuinely differs from CLDR (here, the narrow
weekday representation). Casing is a presentation choice and is left to the
caller — the overlay does not, for example, capitalize stand-alone names.

Overlay locales are keyed precisely (e.g. pt-BR, not pt) so they only affect
the locales they target. To add or extend one, edit
src/translations/community/locales/<locale>.toml (same section schema as the
generated files, but partial) and list it in
src/translations/community/index.toml.

---

Testing

To run the full test suite locally:

1. Manual (recommended for contributors) — install
   tt (tytanic), then:

   node tools/check-invariants.mjs   # structural checks over the data
   tt run                            # Typst tests
   

2. Via the GitHub Actions workflow locally with
   act:

   act --artifact-server-path /tmp/artifact
   

(Regenerating the data needs Node + npm ci; running the tests does not.)

---

Contributing

This package is intentionally opinionated: all locale data comes straight from the Unicode CLDR and is regenerated by tools/generate-cldr.mjs. The TOML files under src/translations/ are build artifacts — editing them by hand has no lasting effect, since the next regeneration overwrites them.

• Canonical locale fixes (wrong or missing translations) should go upstream to CLDR; corrections then flow in automatically on the next data update.
• Regional conventions or styling that CLDR doesn't carry can go in the community overlay (src/translations/community/), which is hand-maintained and survives regeneration.
• Pull requests for bug fixes, the generator, or API enhancements are welcome.
• See cldr-json for the upstream data and structure.
• To run the tests, see the Testing section above.

---

License

MIT © 2026 Jeomhps
CLDR data © Unicode, Inc., used under the Unicode License.

---

Credits

• Unicode CLDR Project
• cldr-json
• tytanic (Typst test runner)