model.dictionary.ts

A dictionary file is the language layer of a module. It gives user-facing names to model fields, insight values, queries, sort options, enums, slices, endpoints, errors, and module-specific UI text.

The current pattern is typed. Dictionary keys should follow the shape of the constant, document filter, slice, and endpoint instead of becoming arbitrary translation strings.

Model Dictionary Pattern

Use modelDictionary for normal document models. The chain usually starts with the model name, then adds field labels, insight labels, document query/sort labels, enum values, signal labels, errors, and custom UI text.

ticket.dictionary.ts

.model

Labels fields from the constant model. Base fields such as id, createdAt, updatedAt, and removedAt are added automatically.

.insight

Labels reporting fields. The base count insight is added automatically.

.query / .sort

Labels document filter options. Base query and sort labels such as any, latest, and oldest are included.

Using Dictionaries

After a dictionary is declared, most code uses it through generated helpers. Client components read translated labels with usePage(), server code throws Err with an error key, and client stores show translated toast messages with msg.

Client UI

Server Error

Client Toast

Extending Generated Dictionaries

When an app extends a generated or library model, extend the generated dictionaries too. Passing ...user.dictionaries keeps the base dictionary entries and lets the app add only its custom fields, endpoints, or phrases.

user.dictionary.ts

Scalar And Service Dictionaries

Choose the dictionary builder by module shape. Document models use modelDictionary, embedded scalar values use scalarDictionary, and service-only modules use serviceDictionary.

modelDictionary

For document models with model, insight, query, sort, slice, endpoint, error, and custom translations.

scalarDictionary

For embedded scalar values. It usually needs only model fields, enum values, errors, or small custom text.

serviceDictionary

For service modules or app-level dictionaries without a document model.

coordinate.dictionary.ts

util.dictionary.ts

Errors, UI Text, And Languages

Use error() for domain errors and translate() for module-specific UI phrases. The translation array order must match the language list exactly.

ticket.dictionary.ts

akamir.dictionary.ts

Practical Rules

Keep dictionary keys aligned with typed constants, filters, slices, and endpoints.

Use clear labels for users, not raw variable names. For example, Due Date is better than due.

Add desc() when the label may appear in generated docs, forms, or tooltips.

Use usePage translation in client UI, Err in server logic, and msg in client stores when showing dictionary text.

Extend generated dictionaries with ...model.dictionaries before adding app-specific translations.

Keep every translation tuple in the same order and length as the language list.