YouBothAgent▾
You — Business rules and flows you own. Read these yourself.
Both — Know the idea; your agent follows the details.
Agent — Conventions and references your agent follows. Look up as needed.
Introduction▾
Tutorials▾
System Architecture▾
Module Convention▾
Scalar Convention▾
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.
methodDescription
.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
- File location: __scalar/<name>/<name>.dictionary.ts
- Import scalarDictionary from '@akanjs/dictionary'
- Import types from constant file using 'import type'
- Initialize with correct language order: ["en", "ko"]
- Define scalar name/description with .of()
- Define all field translations with .model<Type>()
- Define all enum translations with .enum<Type>(name)
- Ensure enum name matches enumOf() name
- Include both label and description for all entries
- Export as 'dictionary'
💡 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