cletter

Locale-correct correspondence, from salutation to closing.

Compose a formal letter from deterministic rules: resolve a document locale, address a recipient, write an application subject, format the date, choose a closing, and prepare a handwritten signature image. Rust, JavaScript, and Python share the same conformance vectors.

import { salutation } from '@corbet-labs/cletter';

salutation('de-ch', 'Frau Dr. Müller');
// Sehr geehrte Frau Dr. Müller

Install

The 0.2.2 JavaScript distribution includes compiled ESM, CommonJS, TypeScript declarations, and a standalone browser module. Node.js 20+ is supported; no TypeScript loader is required.

// CommonJS
const { salutation } = require('@corbet-labs/cletter');

<script type="module">
  import { salutation } from 'https://cdn.jsdelivr.net/npm/@corbet-labs/cletter@0.2.2/dist/browser.js';
  console.log(salutation('de-ch', 'Frau Dr. Müller'));
</script>

Python 3.10+ users can install cletter 0.2.1 from PyPI, including its four component dependencies. This release retains Apache-2.0. See the installation guide for CLI commands and other distribution options. JSR publication and Typst availability are listed there explicitly.

Rust

use cletter::{closing, long_date, resolve_locale, salutation};

let locale = resolve_locale(Some("de"), Some("Zürich, Zug"));
assert_eq!(salutation(&locale, "Frau Dr. Müller"), "Sehr geehrte Frau Dr. Müller");
assert_eq!(closing(&locale, None), "Freundliche Grüsse");
assert_eq!(long_date(&locale, 2026, 9, 7).as_deref(), Some("7. September 2026"));

Python

from cletter import salutation

assert salutation("de-ch", "Frau Dr. Müller") == 'Sehr geehrte Frau Dr. Müller'

API

The API below follows current main. Python 0.2.1 on PyPI predates normalize_locale_id; its other listed Python helpers are available.

Openings and closings have 40 locale entries. Date formatting currently covers German and English variants; other dates fall back to English. Locale IDs are lowercase in tables and outputs; lookups accept mixed case and explicit overrides win. Subject defaults are for job applications; supply a prefix override for other correspondence. The library produces letter components; your application owns the body, layout, and PDF rendering. Spelling transformations require caller-selected prose: preserve exact names, quotations, URLs and source material; use diagnostics when those boundaries are unavailable.

The self-contained Typst facade consumes the same greeting, closing and date helpers as the other ports.

Use normalize_locale_id (normalizeLocaleId in JavaScript) when the caller has selected an explicit locale: " EN_CH " becomes "en-ch" even though that region has no correspondence-table entry. It trims only ASCII space, tab, LF, CR, VT and FF, converts underscores to hyphens and lowercases ASCII letters. Other characters, including U+FEFF and U+0085, remain for caller validation. It does not validate syntax, discard subtags, choose a region or default an empty value. Applications validate their storage shape and declared locales. normalize_language and resolve_locale retain their supported-language and location fallback behavior.

Correspondence family

Development

Behavior is defined by the locale tables and shared conformance vectors. Rust, JavaScript, and Python run the same vectors. Selected CI checks exercise installed JavaScript tarballs, Python wheels and command-line entrypoints, and Typst packages. Release validation records the actual runtime and platform; Linux results do not establish native Windows or macOS coverage. All five Rust crates forbid unsafe code in their own source.

See the release guide for generation, verification, and publication commands.

License

Copyright 2026 Julian Y. Richard Corbet. The 0.3.0 release line is licensed under LGPL-3.0-only [WITH LGPL-3.0-linking-exception](https://github.com/corbet-labs/cletter/blob/main/LICENSES/LGPL-3.0-only WITH LGPL-3.0-linking-exception.txt), with the incorporated GPL version 3. Combined works may link statically or dynamically without relinking duties; library modifications stay LGPL. Applications can use a different license subject to the LGPL's conditions. Previously released and already prepared distributions retain their original grants. The installation examples above refer to those available releases; 0.3.0 has not yet been published to registries.

The existing cdate, cfarewell and cink Typst snapshots remain Apache-2.0; the cgreet snapshot remains MIT OR Apache-2.0. Their files and notices are preserved unchanged.

See the licensing notes for distribution conditions and retained notices.