Message catalogues (spec 6 §19): a bundle's messages files read into a TranslationProvider that t resolves through, and the search that matches a title in every locale the bundle has. More...

#include <algorithm>
#include <cstddef>
#include <expected>
#include <map>
#include <memory>
#include <optional>
#include <string>
#include <string_view>
#include <utility>
#include <variant>
#include <vector>
#include "../render/i18n.hpp"
#include "bundle.hpp"
#include "message.hpp"
#include "value.hpp"

Classes
struct	morph::ui::Catalogue
	One locale's messages, by key, with the patterns already parsed. More...
class	morph::ui::MessageCatalogues
	The message catalogues of one bundle, by locale, and the provider t resolves through. More...
struct	morph::ui::detail::catalogue::TitleParts
	A catalog title's parts: a plain string, or the message key of a {"t": …} reference and its fallback. More...

Functions
std::optional< std::string >	morph::ui::catalogueLocale (std::string_view fileId)
	Reads the locale from a catalogue's id.
std::expected< Catalogue, std::string >	morph::ui::parseCatalogue (std::string_view text)
	Parses a catalogue: a flat JSON object of message key to MessageFormat 2 pattern.
MessageCatalogues	morph::ui::loadCatalogues (Manifest const &manifest, std::map< std::string, std::string, std::less<> > const &files)
	Reads every message catalogue a verified bundle lists.
std::vector< std::string >	morph::ui::textInEveryLocale (MessageCatalogues const &catalogues, std::string_view key, std::string_view fallback)
	A message formatted in every locale the catalogues hold: what a search over titles compares against.
bool	morph::ui::matchesInAnyLocale (MessageCatalogues const &catalogues, std::string_view key, std::string_view fallback, std::string_view query)
	Whether a message contains `query` in any locale the catalogues hold, or in its fallback: a navigator's search, so a user finds a screen by the title they know in any language.
TitleParts	morph::ui::detail::catalogue::titleParts (Json const &title)
	Splits a catalog title into its parts.
std::optional< std::string >	morph::ui::detail::catalogue::formatPattern (std::string_view pattern, std::string const &locale)
	A message pattern formatted with no arguments.
std::string	morph::ui::catalogTitle (CatalogEntry const &entry, MessageCatalogues const *catalogues, std::string_view locale)
	A catalog entry's title in one locale, as a shell's tab or header shows it.
std::vector< std::string >	morph::ui::catalogTitles (CatalogEntry const &entry, MessageCatalogues const *catalogues)
	A catalog entry's title in every locale the catalogues hold: what a search over screen titles compares against.

Variables
constexpr std::size_t	morph::ui::kMaxCatalogueKeys = 16384
	The most keys one catalogue may hold.
constexpr std::string_view	morph::ui::kCataloguePrefix = "i18n/"
	The id prefix of a message catalogue: i18n/LOCALE.json.
constexpr std::string_view	morph::ui::kCatalogueSuffix = ".json"
	The id suffix of a message catalogue.

Detailed Description

Message catalogues (spec 6 §19): a bundle's messages files read into a TranslationProvider that t resolves through, and the search that matches a title in every locale the bundle has.

Specified in docs/spec/ui/catalogue.md.

Definition in file catalogue.hpp.

Function Documentation

◆ catalogueLocale()

std::optional< std::string > morph::ui::catalogueLocale ( std::string_view fileId )

inlinenodiscard

Reads the locale from a catalogue's id.

Parameters

fileId The id, such as i18n/de-AT.json.

Returns: The locale (de-AT), or nothing when the id is not i18n/LOCALE.json with a locale of ASCII letters, digits and - that starts with a letter.

Definition at line 50 of file catalogue.hpp.

◆ parseCatalogue()

std::expected< Catalogue, std::string > morph::ui::parseCatalogue ( std::string_view text )

inlinenodiscard

Parses a catalogue: a flat JSON object of message key to MessageFormat 2 pattern.

Refused: text that is not JSON or nests deeper than kMaxJsonDepth, anything but an object, a must-understand (!) key, a value that is not a string, an empty key or one longer than kMaxNameBytes, and more than kMaxCatalogueKeys keys. A pattern outside the ui/1 subset does not refuse the catalogue: its key is left out and listed in dropped, so t shows the fallback for it.

Parameters

text	The catalogue's JSON text.

Returns: The catalogue, or the reason it is refused.

Definition at line 74 of file catalogue.hpp.

◆ loadCatalogues()

MessageCatalogues morph::ui::loadCatalogues	(	Manifest const &	manifest,
		std::map< std::string, std::string, std::less<> > const &	files )

inlinenodiscard

Reads every message catalogue a verified bundle lists.

A catalogue whose id is not i18n/LOCALE.json, whose bytes are not among files, or that parseCatalogue refuses, is left out, and its locale shows the fallbacks; a pattern outside the subset is dropped. Each is noted in problems(). Nothing is refused later, at a t.

Parameters

manifest	The bundle's manifest (LoadedBundle::manifest).
files	The verified files by content hash (LoadedBundle::files).

Returns: The catalogues.

Definition at line 188 of file catalogue.hpp.

◆ textInEveryLocale()

std::vector< std::string > morph::ui::textInEveryLocale	(	MessageCatalogues const &	catalogues,
		std::string_view	key,
		std::string_view	fallback )

inlinenodiscard

A message formatted in every locale the catalogues hold: what a search over titles compares against.

Parameters

catalogues	The catalogues.
key	The message key.
fallback	The source text, shown for a locale without the key.

Returns: One text per locale, in the order of locales(); the fallback alone when there are no catalogues.

Definition at line 224 of file catalogue.hpp.

◆ matchesInAnyLocale()

bool morph::ui::matchesInAnyLocale	(	MessageCatalogues const &	catalogues,
		std::string_view	key,
		std::string_view	fallback,
		std::string_view	query )

inlinenodiscard

Whether a message contains query in any locale the catalogues hold, or in its fallback: a navigator's search, so a user finds a screen by the title they know in any language.

ASCII letters compare without case; every other byte compares exactly.

Parameters

catalogues	The catalogues.
key	The message key.
fallback	The source text.
query	What the user typed; an empty query matches.

Returns: Whether any locale's text contains it.

Definition at line 264 of file catalogue.hpp.

◆ titleParts()

TitleParts morph::ui::detail::catalogue::titleParts ( Json const & title )

inlinenodiscard

Splits a catalog title into its parts.

Parameters

title The title.

Returns: Its parts; all empty for a title that is neither a string nor an object.

Definition at line 292 of file catalogue.hpp.

◆ formatPattern()

std::optional< std::string > morph::ui::detail::catalogue::formatPattern	(	std::string_view	pattern,
		std::string const &	locale )

inlinenodiscard

A message pattern formatted with no arguments.

Parameters

pattern	The pattern.
locale	The locale.

Returns: The text, or nothing when the pattern does not parse.

Definition at line 318 of file catalogue.hpp.

◆ catalogTitle()

std::string morph::ui::catalogTitle	(	CatalogEntry const &	entry,
		MessageCatalogues const *	catalogues,
		std::string_view	locale )

inlinenodiscard

A catalog entry's title in one locale, as a shell's tab or header shows it.

A string title is shown as is. A message reference ({"t": key, "fallback": …}) is formatted in locale from catalogues — the exact locale's catalogue, then its language's — and is its fallback when no catalogue has the key. A title that is neither, or a reference with no fallback that no catalogue resolves, is the entry's id.

Parameters

entry	The entry.
catalogues	The message catalogues, or null for none.
locale	The BCP 47 locale to format in.

Returns: The title.

Definition at line 337 of file catalogue.hpp.

◆ catalogTitles()

std::vector< std::string > morph::ui::catalogTitles	(	CatalogEntry const &	entry,
		MessageCatalogues const *	catalogues )

inlinenodiscard

A catalog entry's title in every locale the catalogues hold: what a search over screen titles compares against.

With catalogues, a message reference is textInEveryLocale of its key and fallback (the entry's id when it has none). Without, the one title is a string title as is, else a reference's fallback, else the entry's id.

Parameters

entry	The entry.
catalogues	The message catalogues, or null for none.

Returns: The titles; never empty.

Definition at line 365 of file catalogue.hpp.

Variable Documentation

◆ kMaxCatalogueKeys

std::size_t morph::ui::kMaxCatalogueKeys = 16384

inlineconstexpr

The most keys one catalogue may hold.

Definition at line 30 of file catalogue.hpp.

◆ kCataloguePrefix

std::string_view morph::ui::kCataloguePrefix = "i18n/"

inlineconstexpr

The id prefix of a message catalogue: i18n/LOCALE.json.

Definition at line 33 of file catalogue.hpp.

◆ kCatalogueSuffix

std::string_view morph::ui::kCatalogueSuffix = ".json"

inlineconstexpr

The id suffix of a message catalogue.

Definition at line 36 of file catalogue.hpp.

Classes

Functions

Variables

Detailed Description

Function Documentation

◆ catalogueLocale()

◆ parseCatalogue()

◆ loadCatalogues()

◆ textInEveryLocale()

◆ matchesInAnyLocale()

◆ titleParts()

◆ formatPattern()

◆ catalogTitle()

◆ catalogTitles()

Variable Documentation

◆ kMaxCatalogueKeys

◆ kCataloguePrefix

◆ kCatalogueSuffix