Universe

Test Datify

⚠️ Major Breaking Changes in v1.0.0+

  • The user-facing API of Datify has been completely rewritten.
  • Functions like day-name, month-name, etc. are no longer available directly in Datify. They have been moved to datify-core, which Datify uses as its backend. Example migration:
    #import "@preview/datify-core:1.0.0": *
#get-day-name(datetime.today(), lang: "en") // Now available in datify-core
  • The new backend is based on the Unicode CLDR project, providing robust internationalization.
  • If you need to resolve a single day or month name, it is recommended to use datify-core directly. You can also use custom-date-format for this, but it is less practical for single values.
  • The core logic for string transformation now uses a formal language and automata approach, similar to many modern date libraries. This introduces a new quoting system for escaping text in patterns.
  • If you are migrating from a previous version, your code will need to be updated. The old usage is not compatible with this version.

Table of Contents

  1. Overview
  2. Installation
  3. Usage
  4. Supported Languages
  5. Contributing
  6. License
  7. Development & Testing
  8. Planned Features
  9. Glossary

Overview

Datify is a Typst package for flexible, locale-aware date formatting. It leverages datify-core for internationalization and supports CLDR-style date patterns.

Installation

Add Datify to your Typst project (specify the version you want):

#import "@preview/datify:1.0.0": *

Usage

Function Reference

Argument Type Required Default Description
date datetime Yes – The date to format
pattern str No “full” Pattern string or CLDR named pattern
lang str No “en” ISO 639-1 language code (e.g., “en”, “fr”, “es”)

If you only provide lang, the pattern defaults to "full" for that locale. All arguments must be named except for the first (date).

Example usage

#let mydate = datetime(year: 2025, month: 1, day: 5)
#custom-date-format(mydate) // Output: Sunday, January 5, 2025 (in English, full format)
#custom-date-format(mydate, lang: "es") // Output: domingo, 5 de enero de 2025
#custom-date-format(mydate, pattern: "yyyy-MM-dd") // Output: 2025-01-05
#custom-date-format(mydate, pattern: "full", lang: "fr") // Output: dimanche 5 janvier 2025

Pattern Syntax

The pattern argument can be either:

  • A CLDR named pattern ("full", "long", "medium", "short") for locale-appropriate formatting.
  • A custom string pattern using the tokens below.

CLDR Pattern Example

#custom-date-format(mydate, pattern: "full", lang: "fr") // Output: dimanche 5 janvier 2025

Custom Pattern Example

#custom-date-format(mydate, pattern: "EEEE, MMMM dd, yyyy") // Output: Sunday, January 05, 2025
#custom-date-format(mydate, pattern: "EEE, MMM d, yyyy") // Output: Sun, Jan 5, 2025

Format Tokens

Token Description Example Output
EEEE Full weekday name Sunday
EEE Abbreviated weekday name Sun
MMMM Full month name January
MMM Abbreviated month name Jan
MM Month number, 2 digits 01
M Month number, 1-2 digits 1
dd Day of month, 2 digits 05
d Day of month, 1-2 digits 5
yyyy 4-digit year 2025
y Year (same as yyyy) 2025
  • Tokens are case-sensitive.
  • Only the tokens above are supported.

Named Patterns

You can use CLDR-style named patterns: "full", "long", "medium", "short". These will be resolved to locale-appropriate patterns for the given language.

Pattern English (en) French (fr)
full Sunday, January 5, 2025 dimanche 5 janvier 2025
long January 5, 2025 5 janvier 2025
medium Jan 5, 2025 5 janv. 2025
short 1/5/25 05/01/2025

Literal Text in Patterns

To include literal text in patterns, wrap it in single quotes ('). To include a single quote, use '' (two single quotes).

Example Pattern Output
'Today is' EEEE Today is Sunday
yyyy'/'MM'/'dd 2025/01/05
'''Quoted text''' ‘Quoted text’
EEE 'the' dd Sun the 05

⚠️ Important: Always quote literal text to avoid misinterpretation as tokens. While unquoted text may work now, it could cause errors in future versions.

Supported Languages

Datify supports all languages provided by datify-core. If you pass an unsupported language code, an error will be thrown.

Contributing

  • Native speakers wanted! If you notice missing or incorrect translations for a language, please contribute directly to datify-core, which manages all locale data for Datify.
  • Pull requests for bug fixes, improvements, ideas, or feedback are welcome here.
  • For upstream locale data and structure, see cldr-json.

License

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

Development & Testing

To run the full test suite locally, you have two options:

  1. Using tt (tytanic)
    tt run
  2. Using act
    act --artifact-server-path /tmp/artifact

Glossary

  • CLDR: Unicode Common Locale Data Repository, a project for locale-specific data (e.g., date formats, language rules).
  • ISO 639-1: Two-letter codes for representing languages (e.g., en for English, fr for French).
  • Typst: A markup-based typesetting system.