hermes-react

Elegant i18n for React in TypeScript

hermes-react is a TypeScript library for React dedicated to i18n - especially elegant annotated typography, for example romanization of non-latin writing systems - inspired by my general-purpose hermes library.

Installation

TypeScript

The package on NPM is:

@giancosta86/hermes-react

The public API entirely resides in the root package index, so you shouldn't reference specific modules.

CSS stylesheet

The library comes with a ready-made CSS stylesheet - providing typographic enhancements such as pinyin tone colors - which you can optionally reference in your projects.

In particular, if you are using Next.js, you just need to add one line to the import block of your _app.tsx file:

import "@giancosta86/hermes-react/dist/index.css";

Once referenced the CSS stylesheet, if you start decorating characters with the provided metadata - such as the ones in the Pinyin namespace - you'll see them rendered in color by the <AnnotatedText/> component.

Usage

AnnotatedText

<AnnotatedText/> is a component with the following properties:

• text - the text to be formatted

• metadataByChar - mapping each annotated character to its typographic metadata

where metadataByChar is any RMap whose entries have:

• for key, a single character that should be annotated

• for value, the related CharMetadata object containing:

  • the annotation string - to be printed on top of the character

  • optionally, an Iterable of class names used to style the whole character box

The component formats the given text according to the following algorithm:

1. The text is trimmed

2. Any \r\n is converted to \n

3. Every additional \n at the end of a \n\n sequence is ignored

4. The text is split into paragraphs - <p> blocks - separated by \n\n sequences that are used as separators and then ignored

5. Within every paragraph:

   1. \n is mapped to <br/>

   2. for every other character:

      • if the character has metadata in the metadataByChar map:

        • the related annotation string is printed on top of the character

        • the whole structure is packed into a <ruby> tag, styled with the (optional) requested classes

      • otherwise, the character is printed verbatim, with no additional HTML tags

Pinyin - Simplified Chinese

When annotating a pinyin logogram, you can associate to its classes metadata one of the following values (actually, string arrays) of the Pinyin namespace:

• flat

• rising

• fallingRising

• falling

• neuter

If you need more granular control, you can reference the constants declared in the PinyinTone namespace - having the same names but providing just the tone class name in lieu of an array.

If you import the stylesheet provided by the library, the component will render the characters in color.

Glyph character classes

The Glyph namespace provides general-purpose class names - such as latin, nonLatin, phonogram, logogram, ..., which you can use to style your annotated characters.

See also

• hermes - Minimalist i18n in TypeScript

• rimbu - Immutable collections and tools for TypeScript

• Next.js - The React Framework for the Web