Skip to content

ludus::localization

Ludus Wiki · API overview · Browse API

Namespace

Declared in modules/localization/include/ludus/localization/catalog.hpp

Enumerations

Status

enum class Status : uint8
Outcome of every fallible localization operation; failures preserve outputs.

Related types: uint8

Ok

Ok
The operation succeeded and wrote its output.

Invalid

Invalid
Malformed bytes, an invalid handle or a key outside the ID grammar.

Unsupported

Unsupported
A package version, record width or profile this reader does not implement.

Limit

Limit
A size or count exceeds the documented ceiling.

OutOfMemory

OutOfMemory
The allocation domain could not provide the catalog copy.

NotFound

NotFound
The domain or key is absent from this catalog.

WrongCatalog

WrongCatalog
The binding belongs to another prepared catalog.

TokenExhausted

TokenExhausted
The process-local catalog token space is exhausted.

SchemaMismatch

SchemaMismatch
The key exists, but its argument schema differs from the descriptor.

RequiresArguments

RequiresArguments
The message has arguments; it must be formatted, not resolved statically.

InvalidArguments

InvalidArguments
Format: an argument is missing, duplicate, undeclared, of the wrong kind or invalid.

BufferTooSmall

BufferTooSmall
Format: the output span is shorter than FormatResult::RequiredBytes.

NotPrepared

NotPrepared
Format: the dynamic message was not prepared in this formatter context.

BackendUnavailable

BackendUnavailable
No running Unicode host, or a build without LUDUS_BUILD_UNICODE.

LinguisticDataMismatch

LinguisticDataMismatch
The package was cooked with different ICU/CLDR/Unicode data than the runtime's.

BackendFailure

BackendFailure
ICU rejected a pattern or format that cooking had accepted.

Declared in modules/localization/include/ludus/localization/catalog.hpp

ArgumentType

enum class ArgumentType : uint8
Value category of one ludus-icu-mf1-v1 message argument.

Related types: uint8

Text

Text
Counted literal UTF-8, never interpreted as a message.

Count

Count
int64 within the declared bounds; plural selector or integer display.

Number

Number
Finite float64 measurement within the declared bounds; display only.

Enum

Enum
One of the declared ASCII tokens, selected with select.

Declared in modules/localization/include/ludus/localization/catalog.hpp

TextOrigin

enum class TextOrigin : uint8
Who produces a Text argument; user text is filtered more strictly by L2 formatting.

Related types: uint8

Game

Game
Authored game content.

User

User
Typed by a player; controls and bidi overrides are rejected.

Declared in modules/localization/include/ludus/localization/catalog.hpp

UnknownPolicy

enum class UnknownPolicy : uint8
What an Enum argument does with a token outside its declaration.

Related types: uint8

Other

Other
Select the other branch.

Reject

Reject
Fail argument validation.

Declared in modules/localization/include/ludus/localization/catalog.hpp

Origin

enum class Origin : uint8
Which catalog provided a resolved message for the requested locale.

Related types: uint8

Source

Source
The catalog is the source locale's.

Translation

Translation
The requested locale's own approved translation.

SourceFallback

SourceFallback
The source locale's message, reached through explicit fallback.

Fallback

Fallback
Another translated locale on the manifest's fallback path.

Declared in modules/localization/include/ludus/localization/catalog.hpp

ArgumentValueKind

enum class ArgumentValueKind : uint8
Value representation supplied for one argument; the schema decides which kinds it accepts.

Related types: uint8

Text

Text
Counted UTF-8: a Text argument or an Enum token.

Integer

Integer
int64: a Count, or a Number with an integral value.

Number

Number
Finite float64: a Number only.

Declared in modules/localization/include/ludus/localization/formatter.hpp

Constants and variables

kMaxCatalogBytes

constexpr usize ludus::localization::kMaxCatalogBytes = usize{32} * 1024 * 1024

Related types: usize

Declared in modules/localization/include/ludus/localization/catalog.hpp

kMaxMessages

constexpr uint32 ludus::localization::kMaxMessages = 65536

Related types: uint32

Declared in modules/localization/include/ludus/localization/catalog.hpp

kMaxTextBytes

constexpr usize ludus::localization::kMaxTextBytes = usize{64} * 1024

Related types: usize

Declared in modules/localization/include/ludus/localization/catalog.hpp

kMaxIdentifierBytes

constexpr usize ludus::localization::kMaxIdentifierBytes = 128

Related types: usize

Declared in modules/localization/include/ludus/localization/catalog.hpp

MAX_PATTERN_BYTES

constexpr usize ludus::localization::MAX_PATTERN_BYTES = usize{16} * 1024
Largest dynamic ludus-icu-mf1-v1 pattern stored in a package, in UTF-8 bytes.

Related types: usize

Declared in modules/localization/include/ludus/localization/catalog.hpp

MAX_ARGUMENTS

constexpr usize ludus::localization::MAX_ARGUMENTS = 32
Most argument declarations one ludus-icu-mf1-v1 message may have.

Related types: usize

Declared in modules/localization/include/ludus/localization/catalog.hpp

MAX_FALLBACK_PROVIDERS

constexpr usize ludus::localization::MAX_FALLBACK_PROVIDERS = 8
Most catalogs on one locale's message-fallback path, including the locale itself.

Related types: usize

Declared in modules/localization/include/ludus/localization/catalog.hpp

MAX_FORMATTED_BYTES

constexpr usize ludus::localization::MAX_FORMATTED_BYTES = usize{64} * 1024
Largest formatted message, in UTF-8 bytes; a longer result returns Limit.

Related types: usize

Declared in modules/localization/include/ludus/localization/formatter.hpp

MAX_PREPARED_MESSAGES

constexpr usize ludus::localization::MAX_PREPARED_MESSAGES = 4096
Most bindings one formatter context may prepare.

Related types: usize

Declared in modules/localization/include/ludus/localization/formatter.hpp

Functions

PrepareCatalog

Status ludus::localization::PrepareCatalog(std::span< const uint8 > bytes, const foundation::AllocationDomain &domain, Catalog &output, Diagnostic &diagnostic)
Validates a portable cooked catalog and copies the caller's bytes.
Accepts package version 1 (ludus-static-utf8-v1) and version 2 (ludus-icu-mf1-v1, static text plus dynamic patterns and their argument schemas); see docs/modules/localization.md for both layouts. Every offset, count, label, key order, UTF-8 range, schema field and provider index is checked before one allocation from domain. Transactional, including an input that borrows the previous output. No I/O and no ICU. Caller must not mutate input concurrently. Failure preserves output; diagnostic reports a byte offset, including malformed cooked files without allocating.

Related types: foundation::AllocationDomain · Catalog · uint8 · Status · Diagnostic

Declared in modules/localization/include/ludus/localization/catalog.hpp

MakeTextArgument

constexpr ArgumentValue ludus::localization::MakeTextArgument(std::string_view name, std::string_view text) noexcept
Text argument: literal UTF-8, never interpreted as a message.

Related types: ArgumentValue

Declared in modules/localization/include/ludus/localization/formatter.hpp

MakeEnumArgument

constexpr ArgumentValue ludus::localization::MakeEnumArgument(std::string_view name, std::string_view token) noexcept
Enum argument: one declared token, or any token for an unknown: other declaration.

Related types: ArgumentValue

Declared in modules/localization/include/ludus/localization/formatter.hpp

MakeCountArgument

constexpr ArgumentValue ludus::localization::MakeCountArgument(std::string_view name, int64 count) noexcept
Count argument: a plural/ordinal selector or integer display within the declared bounds.

Related types: int64 · ArgumentValue

Declared in modules/localization/include/ludus/localization/formatter.hpp

MakeNumberArgument

constexpr ArgumentValue ludus::localization::MakeNumberArgument(std::string_view name, float64 number) noexcept
Number argument: a finite measurement within the declared bounds; display only.

Related types: float64 · ArgumentValue

Declared in modules/localization/include/ludus/localization/formatter.hpp

PrepareFormatterContext

Status ludus::localization::PrepareFormatterContext(const Catalog &lease, std::span< const MessageBinding > messages, const foundation::AllocationDomain &domain, FormatterContext &outContext)
Parses the dynamic patterns of messages once, in their provider locales.
A cold operation: prepare a view's dynamic set before it becomes visible. Static bindings and duplicates are accepted and need no preparation. Checks, in order: a valid version 2 lease (Invalid, Unsupported), the message count (Limit), every binding against this lease (WrongCatalog), a running Unicode host (BackendUnavailable, also in builds without ICU), the package's linguistic-data label against the running ICU (LinguisticDataMismatch), the context storage from domain (OutOfMemory) and ICU pattern construction (BackendFailure). ICU allocation failure is fatal, never reported.
ParameterDescription
lease
Catalog to retain; copied, so the caller may replace its own.
messages
Bindings of lease to prepare, at most MAX_PREPARED_MESSAGES.
domain
Storage for the context state. Borrowed; it must outlive the context.
outContext
Replaced only on Ok; every failure leaves it unchanged.

Related types: foundation::AllocationDomain · Catalog · FormatterContext · MessageBinding · Status

Declared in modules/localization/include/ludus/localization/formatter.hpp

Format

Status ludus::localization::Format(FormatterContext &inoutContext, MessageBinding binding, std::span< const ArgumentValue > arguments, std::span< char > output, FormatResult &outResult)
Formats one message with its complete argument schema into caller bytes.
Validates before ICU: every declared argument exactly once with an accepted kind; Count and Number within bounds, Number finite; Text valid UTF-8 without NUL within max_bytes, and user text without C0/C1 controls, bidi embeddings/overrides (U+202A-U+202E) or isolates (U+2066-U+2069); Enum tokens declared, or mapped to other for unknown: other. Inserted text is wrapped in FSI (U+2068) ... PDI (U+2069). A static record copies its cooked text without ICU; it still rejects arguments.
ParameterDescription
inoutContext
Prepared context; its ICU scratch is reused.
binding
Binding made by the context's lease (or a copy of it).
arguments
Values in any order.
output
Receives complete UTF-8 on Ok only; never NUL-terminated or truncated.
outResult
Reset on every call; see FormatResult.

Returns

Ok; Invalid for an invalid context; WrongCatalog; NotPrepared for an unprepared dynamic message; InvalidArguments; BufferTooSmall with RequiredBytes; Limit above MAX_FORMATTED_BYTES; BackendFailure. Every failure leaves the output bytes unchanged.

Related types: FormatterContext · MessageBinding · Status · ArgumentValue · FormatResult

Declared in modules/localization/include/ludus/localization/formatter.hpp

Aliases

int64

using ludus::foundation::core::int64 = std::int64_t
Exact 64-bit signed integer for explicit-width values.

Declared in modules/localization/include/ludus/localization/catalog.hpp

uint32

using ludus::foundation::core::uint32 = std::uint32_t
Exact 32-bit unsigned integer for explicit-width values.

Declared in modules/localization/include/ludus/localization/catalog.hpp

uint64

using ludus::foundation::core::uint64 = std::uint64_t
Exact 64-bit unsigned integer for explicit-width values.

Declared in modules/localization/include/ludus/localization/catalog.hpp

uint8

using ludus::foundation::core::uint8 = std::uint8_t
Exact 8-bit unsigned integer for explicit-width values.

Declared in modules/localization/include/ludus/localization/catalog.hpp

usize

using ludus::foundation::core::usize = std::size_t
Native unsigned size/index type; matches sizeof and container sizes, not a wire format.

Declared in modules/localization/include/ludus/localization/catalog.hpp

float64

using ludus::foundation::core::float64 = double
IEEE binary64 scalar; does not select rounding, trap or denormal policy.

Declared in modules/localization/include/ludus/localization/formatter.hpp