# Showing text [Text and translation](https://opencharacterformat.org/guides/text-and-translation/) explains where text lives and how each key is built. This page shows the shortcut: `@opencharacter/text`, a small helper that builds the keys from engine output and formats the messages for you. The engine still returns no text; the helper is on your app's side, and you can drop it for your own code at any time. It's a reference helper, not part of the spec: another engine's output works with it too, and a port needn't have one. ## A text bundle Build one bundle per player language from the packs' text and the spec's standard text: ```ts import { createText } from '@opencharacter/text'; import packsEn from '@opencharacter/packs/i18n/en'; import specEn from '@opencharacter/spec/i18n/en'; const text = createText({ languages: ['en'], // lookup order, the player's language first: ['de', 'en'] packs: { en: packsEn }, // by language, then pack ID spec: { en: specEn }, contentTypes: ruleset.contentTypes, // optional: field defaults for content cards content: ruleset.content, // optional: content types for headlines display: ruleset.rules.display, // optional: field formats for headlines }); ``` - `packs` is keyed by language, then pack ID, the shape of `@opencharacter/packs/i18n/`. A single pack's text goes in as `{ en: { '5e-srd-5.1': srdEn } }`; a character's homebrew text under the pack ID `homebrew` (`character.homebrew.i18n.en`). - A key missing in every listed language falls back to any other language the bundle holds for that pack, so a pack's default language fills the gaps of a partial translation. - Messages are formatted with ICU MessageFormat (`intl-messageformat`), in the language they were found in. - A name that's missing comes back as the ID you passed, never as an error, so a gap shows up on screen instead of breaking it. `text.message(pack, key)` and `text.specMessage(key)` return `undefined` when you want to know. ## Names ```ts text.content('5e-srd-5.1:armor.shield'); // 'Shield' text.copy({ item: '5e-srd-5.1:weapons.longsword', templates: ['5e-srd-5.1:magic-items.weapon-plus-one'], }); // 'Longsword +1' text.field('5e-srd-5.1:combat.ac'); // 'Armor Class' text.field('5e-srd-5.1:combat.ac', { short: true }); // 'AC' text.type('5e-srd-5.1:weapon'); // 'Weapon' text.tag('5e-srd-5.1:save.int'); // 'Intelligence saving throw' text.tag('save.int', '5e-srd-5.1'); // the same, for a tag as a set field holds it text.setMember('skill.arcana', '5e-srd-5.1'); // 'Arcana': content, else field, else tag, else the ID text.action('5e-srd-5.1:features.fighter.second-wind#second-wind'); // 'Second Wind' text.band('fitd-scoundrel:action', 'partial'); // 'Partial success' ``` ## Content cards A spell, a weapon or a feat reads best as a card: a header from its mechanics, then its text. Packs write the header as a **block**, a text template per content type, so you never lay one out from field names: ```ts const fireBolt = ruleset.content['5e-srd-5.1:spells.fire-bolt']; text.contentBlock(fireBolt); // '**Fire Bolt** — *Evocation cantrip* · 1 action · 120 ft · V, S · Instantaneous' text.contentCard(fireBolt); // the block, a blank line, then the description: 'You hurl a mote of fire at a creature …' text.value('5e-srd-5.1:spell', 'school', 'evocation'); // 'Evocation' ``` - **Show `contentCard`** for an item's card. It is Markdown: the block and the description, or whichever the item has; `undefined` when it has neither. `contentBlock` is the header alone, `undefined` when the pack has no block for the item. - **Pass the item as the ruleset holds it** (`ruleset.content[id]`). For a copy on a sheet, also pass the copy, `{ templates, fields, state, computed }` (`computed` from computeSheet's `copies[entry]`), so the card names a Longsword +1 and can show the copy's state. - **Give the bundle `contentTypes`** (`ruleset.contentTypes`), or pass the item's type as the third argument: a field the item leaves out then reads as its declared default (a Fate stunt's `action: any`), as the rules read it. - **Render the Markdown**, or show it as plain text, as you do descriptions. - **A field the player names** (a orc-2e Lore of their city) has `name` on its computeSheet value: pass it, `text.field(id, { name: sheet.values[id].name })` ("Absalom Lore"); without it the text reads "Lore". - **Templates have cards too**: pass a template as the ruleset holds it (a orc-2e rune, `type: 'template'`) and `contentCard` gives its own block ("**Flaming rune** — _Rune 8_ · Magical, Property rune · 500 gp") and description. - `text.value(type, field, value)` names an enum value outside a card, for a filter or a column. A rules-level field's enum value is `text.fieldValue(field, value)` (`fields..values..name`: `creature.size`'s `medium` is "Medium"), and an action parameter's `text.paramValue(action, param, value)` (`.params..values..name`). ## Forms: item fields and parameters A form labels each input with the pack's text, never a humanized ID: ```ts text.typeField('mork-borg-core:weapon', 'attackDrModifier'); // 'Attack DR modifier' text.typeFieldDescription('5e-srd-5.1:armor', 'maxDex'); // 'The most Dexterity modifier AC adds.' text.templateField('5e-srd-5.1:acBonus'); // 'AC bonus', for a custom template's form text.param('mork-borg-core:test', 'dr'); // 'Difficulty rating (DR)' text.paramDescription('mork-borg-core:test', 'dr'); // 'The target to beat. 12 for most rolls; the GM raises or lowers it.' ``` - **Every item field has a name** (`types..fields..name`); a hint (`.description`) is optional, one line, for help text under the input. Missing text falls back to the field's ID; a missing hint is `undefined`. - **A parameter's hint** is `.params..description`, optional. `action` is `needs.action`'s form, so an inline action is `#`. A parameter with an explicit `label` key is named by `text.lookup` with that key. ## Headlines A character list wants a line under each name: "Level 3 Hill dwarf Wizard", not the pack's name. Each pack words it as its `headline`, a text template, so your app needs no code per game: ```ts const sheet = computeSheet(ruleset, character); text.headline(sheet, character); // 'Level 3 Hill dwarf Wizard' text.headline(sheet, character) ?? text.pack(character.packs[0].id); // with a fallback ``` | Pack | A finished character | While it's created | | -------------- | -------------------------------------------------------------------------------- | -------------------------- | | 5E SRD | "Level 3 Hill dwarf Wizard", "Hill dwarf Wizard 2 / Fighter 1", "Goblin, CR 1/4" | "Dwarf", then "Hill dwarf" | | orc-2e | "Level 2 Elf Rogue" | "Elf" | | FitD scoundrel | a table's own playbook: "Bruiser", "Bruiser of the Ravens" with the crew's name | nothing without a playbook | | FitD crew | "Tier 1", or "Tier 1 Shadows" with a table's own crew type | "Tier 0" | | Mothership | "Marine" | nothing before a class | | Fate Core | the high concept | nothing before one | | MÖRK BORG | "Heretical Priest", "Classless", "Ancient Gore-Hound" | nothing before a class | - **`undefined` means fall back:** no pack has a headline, or it words nothing yet (a sheet with nothing picked). Show the pack's name, or nothing. - **Pass the character file** for its packs' order (the last pack with a headline words it, homebrew last), its copies' templates and state (a class's level). - **Give the bundle `content` and `display`** (`ruleset.content`, `ruleset.rules.display`): without `content` a headline can't find the character's race or class; without `display` a number shows as is ("CR 0.25", not "CR 1/4"). - **Linked characters' names are yours:** the format doesn't name characters, so pass the names of the characters filling its link slots, by slot ID: `text.headline(sheet, ash, { links: { 'fitd-scoundrel:crew': 'the Ravens' } })` is "Bruiser of the Ravens". - It's plain text on one line: no Markdown, spaces collapsed. ## Choices A choice's prompt comes from its **owner**, never from its path. Pass any entry of `computeSheet`'s `choices` (or a pause's `needs.choice`): ```ts const sheet = computeSheet(ruleset, marine); for (const choice of sheet.choices) console.log(text.choicePrompt(choice)); // 'Choose one Expert skill or two Trained skills' // 'Choose two Trained skills' (owner: …classes.marine.choices.bonus-skills.options.trained) ``` A slot of a slotted choice is worded with its number: a wizard's spellbook slots read "Choose six 1st-level spells for your spellbook", then "Choose two spells for your spellbook (level 2)". An option is labeled by `text.option(id, context)`, whatever its kind: | Option ID | Label from | | ------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------- | | `#done` | the spec's `actions.options.done.name` ("Done"); over pending choices (`context.choice`) `actions.options.done.pending.name` ("Skip the rest") | | `#