Scalar Dictionary

The dictionary file (*.dictionary.ts) provides internationalization for your scalar. Using the scalarDictionary() builder pattern, you define translations for the scalar name, field labels, descriptions, and enum values.

This guide covers the scalarDictionary() syntax, chaining methods, and best practices for defining translations.

🌐Key Benefits

End-to-end type safety
Fluent builder pattern
Automatic validation via generics
Multi-language support

📁File Structure

Scalar Dictionary Builder

The scalarDictionary() function creates a type-safe dictionary using a fluent builder pattern.

method	Description	Example
.of((t) => ...)	Define scalar name & description.
.model<T>((t) => ...)	Define field translations.
.enum<T>(name, (t) => ...)	Define enum value translations.

.of((t) => ...)

Define scalar name & description.

.model<T>((t) => ...)

Define field translations.

.enum<T>(name, (t) => ...)

Define enum value translations.

Translation Format

Each translation uses the t() function with an array of values matching the language order.

Pattern

Translation Format

Each translation uses the t() function with an array of values. The array order matches the language order defined in scalarDictionary().

Translation Pattern

Method	Purpose	Example
`t([...])`	Define the label/name	`t(["Status", "상태"])`
`.desc([...])`	Define the description	`.desc(["Current status", "현재 상태"])`

Both label and description are required for complete internationalization support.

Complete Example

price.dictionary.ts

Enum Name Matching

The first argument to .enum() must match the name used in enumOf() from the constant file. This ensures proper type checking and runtime resolution.

constant.ts

dictionary.ts

Important: The enum name string must exactly match the first argument of enumOf(). For example, enumOf("journey", [...]) requires .enum<Journey>("journey", ...).

Type Imports

Always import types from the constant file to ensure type safety. The generic parameters enforce that all fields and enum values have translations.

Import Pattern

✓

import type: Use 'import type' for type-only imports. This ensures no runtime code is included.

✓

.model<Type>: Provides autocomplete for field names and validates that all fields are translated.

✓

.enum<Type>: Provides autocomplete for enum values and validates that all values are translated.

Common Mistakes

Avoid these common mistakes when defining scalar dictionaries:

Issue	Wrong	Correct
Missing .desc()	`t(["Label", "레이블"])`	`t(["Label", "레이블"]).desc(["Desc", "설명"])`
Wrong enum name	`.enum<Journey>("Journey", ...)`	`.enum<Journey>("journey", ...)`
Missing export	`const dictionary = ...`	`export const dictionary = ...`
Wrong array order	`t(["한국어", "English"])`	`t(["English", "한국어"])`
Missing field	`// TypeScript error`	`All fields defined`

Best Practices

✓Always Use Type Generics

Use .model<Type> and .enum<Type> to ensure TypeScript validates all fields and values are translated.

✓Consistent Language Order

Always use the same language order (e.g., ["en", "ko"]) across all dictionaries in your project.

✓Meaningful Descriptions

Provide helpful descriptions that explain the field's purpose, not just repeat the label.

✓Export as 'dictionary'

Use the standard export name 'dictionary' for consistency with the framework's auto-import system.

Implementation Checklist

💡 Pro Tips:

• TypeScript will show errors if you miss any fields or enum values - use this to your advantage!
• The dictionary is used for UI labels, form validation messages, and API documentation
• Keep descriptions concise but informative - they appear in tooltips and help text